Text-to-Speech (TTS)

Convert text to speech with voice and speed control. Two integrations: the volcengine-tts series uses /v1/audio/speech (JSON request in, binary audio stream out); MiniMax Speech uses /v1/chat/completions (chat format, audio returned as base64).

voice and speed are model-specific fields common to TTS models; available models and current prices are subject to the Model Plaza.

Common Request Structure

All /v1/audio/speech audio models share the same request skeleton (MiniMax Speech uses the chat endpoint — see "MiniMax Speech Format" below):

curl https://api-model.shuntianchuang.cn/v1/audio/speech \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-name>",
    "input": "<text / description>",
    "response_format": "<output-format>"
  }' \
  -o output.<format>
FieldTypeRequiredNotes
modelstringYesModel name; available audio models per the Model Plaza
inputstringYesText input: for TTS the text to synthesize; for BGM / Song a music description or inspiration prompt
response_formatstringDependsOutput audio format; allowed values and whether it is required vary by model — see each capability section

voice, speed, and metadata (a vendor extension pass-through object) are model-specific fields — see "Volcengine Format" in each capability section.

Response: on success a binary audio stream is returned — save it as a file in the requested format (e.g. -o speech.mp3); on failure a JSON error body is returned — check it against the error code reference.

NOTE

On a successful /v1/audio/speech call, the response headers carry billing info: X-Audio-Duration (audio duration, seconds), X-TTS-Chars (input character count), X-Prompt-Tokens / X-Completion-Tokens / X-Total-Tokens (token usage), and X-Usage (full usage JSON). For MiniMax Speech (chat endpoint), usage is in the response JSON's usage field. Cost details are also available in the console's "Usage Logs".

WARNING

Music generation models (BGM / Song) take about 30–60 seconds; set the client timeout to at least 120 seconds.

Speech Synthesis (TTS)

Text to speech with voice and speed control; voice and speed are common model-specific fields for TTS models.

Volcengine Format

Example models: volcengine-tts-v1 / volcengine-tts-v2; below we use volcengine-tts-v2:

FieldTypeRequiredNotes
modelstringYesvolcengine-tts-v2 (seed-tts-2.0) or volcengine-tts-v1 (seed-tts-1.0)
inputstringYesText to synthesize
voicestringYesVoice ID, see common voices below
response_formatstringNoOutput format, defaults to mp3; mp3 / wav / ogg_opus / pcm
speedfloatNoSpeed multiplier, 0.5–2.0, defaults to 1.0
metadata.resource_idstringNoUpstream resource version, e.g. seed-tts-2.0
metadata.emotionstringNoEmotion (e.g. happy); only supported by multi-emotion voices
metadata.sample_rateintNoSample rate, 8000–48000

Model-specific parameters are passed through the metadata object; omit it if not needed.

Common voices (note the v1 / v2 exclusivity):

Voice IDNotes
zh_female_vv_uranus_bigttsFemale, gentle (TTS v2 only)
zh_male_JingQiangKanye_uranus_bigttsMale, elite (TTS v2 only)
zh_male_jingqiangkanye_emo_mars_bigttsMale, emotional (TTS v1)
zh_female_qingxinnvsheng_mars_bigttsFemale, fresh (TTS v1)
TIP
cURL
Python (openai)
Node.js (openai)
# The response body IS the audio file content; save it directly
curl https://api-model.shuntianchuang.cn/v1/audio/speech \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine-tts-v2",
    "input": "Hello, welcome to the Shuntianchuang API model service.",
    "voice": "zh_female_vv_uranus_bigtts",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  -o speech.mp3

Example models: minimax-speech-2.8-hd / minimax-speech-2.8-turbo / minimax-speech-2.6-hd / minimax-speech-2.6-turbo / minimax-speech-02-hd / minimax-speech-02-turbo (below we use minimax-speech-2.6-turbo).

NOTE

This format differs from the /v1/audio/speech skeleton above: it reuses the chat endpoint POST /v1/chat/completions, the text to synthesize goes in messages, and voice parameters are passed through in the metadata extension object; the response is JSON, with the audio returned as a Base64 data URL in message.content — decode it to get the audio file.

FieldTypeRequiredNotes
modelstringYesminimax-speech-* series, e.g. minimax-speech-2.6-turbo
messagesarrayYesThe text to synthesize; all content is concatenated and read in order
voicestringNoShorthand for the voice ID, equivalent to metadata.voice_setting.voice_id; defaults to female-shaonv
metadata.voice_settingobjectNoVoice and tone: voice_id (voice ID), speed (0.5–2, default 1.0), vol (volume 0–10), pitch (-12–12), emotion (happy / sad / angry / fearful / disgusted / surprised / calm / fluent), text_normalization (number normalization), latex_read (read LaTeX aloud; formulas must be wrapped in $$, single $ has no effect)
metadata.audio_settingobjectNoAudio parameters: format (mp3 / wav only, defaults to wav 16000Hz), sample_rate (8000–44100), bitrate (mp3 only; accepted but upstream always outputs a 128k stream), channel (1 / 2, upstream always returns mono)
metadata.pronunciation_dictobjectNoPronunciation replacement (slash style): {"tone": ["还/huan2"]} (⚠️ tested unreliable — pinyin is read literally or loses its tone; to force a pronunciation use the inline bracket syntax in the text: replace the character with (pinyin+tone number), e.g. 我会(huan2)你钱。 reads as "我会huán你钱")
metadata.language_booststringNoPass "auto" to auto-detect the language
metadata.voice_modifyobjectNoVoice adjustment: pitch / intensity / timbre (-100–100), sound_effects (e.g. lofi_telephone)
metadata.subtitle_enableboolNotrue returns subtitles, URL at message.subtitle_file (time-limited — transfer promptly)
metadata.subtitle_typestringNoSubtitle granularity: sentence / word
metadata.aigc_watermarkboolNoWhether to add an AIGC watermark (a short watermark tone is appended to the end of the audio, so a slightly longer file is expected)

Response (chat format):

{
  "model": "minimax-speech-2.6-turbo",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "data:audio/mpeg;base64,//NExAA...",
        "subtitle_file": "https://.../xxx.titles?Expires=..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 180, "completion_tokens": 0, "total_tokens": 180 }
}
  • message.content: data:audio/<format>;base64,<data> — strip the prefix before the comma and Base64-decode to get the audio file
  • message.subtitle_file: subtitle URL (returned when subtitle_enable is on)
  • usage.prompt_tokens: tokens consumed by this call, the billing basis

Billing: by token, tokens consumed = character count × 20 (turbo) / × 35 (hd), where Chinese characters count as 2 and English letters / digits / punctuation as 1. Example: 「你好世界。」= 9 characters = 180 tokens on turbo. Amounts are subject to Model Plaza prices.

WARNING

Tested limits: the top-level response_format field is not supported (the gateway rejects it with 500 — set the output format via metadata.audio_setting.format instead); format supports only mp3 / wav (anything else returns 400); without audio_setting the default output is wav 16000Hz; latex_read formulas must be wrapped in $$ (a single $ gets read out literally; exponents are spoken as digits, e.g. r² as "r2"); pronunciation_dict.tone accepts only slash-style entries (array-pair style like [["还","huan2"]] returns 400) and tested unreliable (huan2 is spoken literally; huán loses its tone and reads as first tone) — to force a pronunciation, use the inline bracket syntax in the text instead: replace the character with (pinyin+tone number), e.g. 我会(huan2)你钱。 is read as "我会huán你钱"; emotion: "whisper" is not supported by any model; timbre_weights mixed voices are not yet available; stream streaming is not supported. Unsupported parameters return a clear error — actual behavior is authoritative.

cURL
Python (openai)
Node.js (openai)
curl https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.6-turbo",
    "messages": [
      { "role": "user", "content": "我会(huan2)你钱。圆面积是$$\\pi r^2$$平方米。" }
    ],
    "metadata": {
      "voice_setting": { "voice_id": "female-shaonv", "speed": 1.2, "latex_read": true },
      "audio_setting": { "format": "mp3", "sample_rate": 32000 },
      "subtitle_enable": true
    }
  }'
# Inline pronunciation: replace the character with (pinyin+tone number) — "还(huan2)" is read as huán;
# LaTeX formulas wrapped in $$ + latex_read are read as formulas (exponents spoken as digits)
# message.content in the response JSON is "data:audio/mpeg;base64,..."; decode it to get the mp3