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>
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.
Example models: volcengine-tts-v1 / volcengine-tts-v2; below we use volcengine-tts-v2:
Model-specific parameters are passed through the metadata object; omit it if not needed.
Common voices (note the v1 / v2 exclusivity):
# 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
from openai import OpenAI
client = OpenAI(
api_key="sk-your-token",
base_url="https://api-model.shuntianchuang.cn/v1",
)
with client.audio.speech.with_streaming_response.create(
model="volcengine-tts-v2",
voice="zh_female_vv_uranus_bigtts",
input="Hello, welcome to the Shuntianchuang API model service.",
response_format="mp3",
speed=1.0,
) as response:
response.stream_to_file("speech.mp3")
import OpenAI from 'openai';
import fs from 'node:fs';
const client = new OpenAI({
apiKey: 'sk-your-token',
baseURL: 'https://api-model.shuntianchuang.cn/v1',
});
const response = await client.audio.speech.create({
model: 'volcengine-tts-v2',
voice: 'zh_female_vv_uranus_bigtts',
input: 'Hello, welcome to the Shuntianchuang API model service.',
response_format: 'mp3',
speed: 1.0,
});
// The response body IS the audio file content; write it to disk directly
fs.writeFileSync('speech.mp3', Buffer.from(await response.arrayBuffer()));
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.
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 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
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-token",
base_url="https://api-model.shuntianchuang.cn/v1",
)
resp = client.chat.completions.create(
model="minimax-speech-2.6-turbo",
# Chinese prompt works best for the upstream model; (huan2) forces 还 to read huán,
# and the $$-wrapped LaTeX formula is read as a formula with latex_read on
messages=[{"role": "user", "content": "我会(huan2)你钱。圆面积是$$\\pi r^2$$平方米。"}],
extra_body={ # metadata is an extension parameter; the openai SDK passes it via extra_body
"metadata": {
"voice_setting": {"voice_id": "female-shaonv", "speed": 1.2, "latex_read": True},
"audio_setting": {"format": "mp3", "sample_rate": 32000},
"subtitle_enable": True,
}
},
)
message = resp.choices[0].message
print("tokens used:", resp.usage.prompt_tokens)
# Decode the audio and save it to a file
_, b64_data = message.content.split(",", 1)
with open("speech.mp3", "wb") as f:
f.write(base64.b64decode(b64_data))
print("subtitle URL:", getattr(message, "subtitle_file", None) or "not enabled")
import OpenAI from 'openai';
import fs from 'node:fs';
const client = new OpenAI({
apiKey: 'sk-your-token',
baseURL: 'https://api-model.shuntianchuang.cn/v1',
});
// metadata is an extension parameter; put it directly in the request body
// (huan2) forces 还 to read huán; the $$-wrapped LaTeX formula is read as a formula with latex_read on
const resp = await client.chat.completions.create({
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,
},
});
const message = resp.choices[0].message;
console.log('tokens used:', resp.usage?.prompt_tokens);
// Decode the audio and save it to a file
const base64Data = message.content.split(',')[1];
fs.writeFileSync('speech.mp3', Buffer.from(base64Data, 'base64'));
console.log('subtitle URL:', message.subtitle_file ?? 'not enabled');