Legacy Guide (Sync API)
NOTE
This page is for existing users who integrated before the platform upgrade and generate music through the synchronous /v1/audio/speech endpoint (models volcengine-bgm / volcengine-song); existing calls keep working. MiniMax Music (chat streaming) is documented on the MiniMax Format page. For new projects, prefer the new async task API (doubao-music-bgm / doubao-music-song), which supports batch submission and centralized task-queue management.
volcengine-bgm (text to instrumental) and volcengine-song (text to vocal song) are called through the synchronous /v1/audio/speech endpoint: the request blocks until the audio is fully generated and returns the binary directly. 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 :
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.
Background Music (BGM)
Generate instrumental background music from a text description; duration and other upstream parameters are passed through the metadata extension object.
Example model: volcengine-bgm. The description supports Chinese only — you can describe genre, mood, scene, instruments, etc.:
curl -X POST https://api-model.shuntianchuang.cn/v1/audio/speech \
-H "Authorization: Bearer sk-your-token" \
-H "Content-Type: application/json" \
-d '{
"model": "volcengine-bgm",
"input": "轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景",
"response_format": "wav",
"metadata": {
"duration": 60,
"enable_input_rewrite": false
}
}' \
--output bgm.wav
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/audio/speech",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={
"model": "volcengine-bgm",
# input supports Chinese only (upstream requirement)
"input": "轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景",
"response_format": "wav",
"metadata": {"duration": 60, "enable_input_rewrite": False},
},
timeout=120, # BGM generation takes 30-60s; use a generous timeout
)
resp.raise_for_status()
with open("bgm.wav", "wb") as f:
f.write(resp.content)
import fs from 'node:fs';
// metadata is a vendor extension parameter; use native fetch (Node.js 18+)
const resp = await fetch(
'https://api-model.shuntianchuang.cn/v1/audio/speech',
{
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'volcengine-bgm',
// input supports Chinese only (upstream requirement)
input: '轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景',
response_format: 'wav',
metadata: { duration: 60, enable_input_rewrite: false },
}),
},
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
fs.writeFileSync('bgm.wav', Buffer.from(await resp.arrayBuffer()));
NOTE
In our testing BGM and Song only support wav output: save files with a .wav extension; transcode yourself if you need mp3, e.g. ffmpeg -i bgm.wav bgm.mp3.
TIP
Richer descriptions produce better results. Organize along four dimensions: genre (pop / classical / jazz / electronic…), mood (relaxed / melancholic / uplifting / serene…), scene (café / wedding / workout / meditation…), instruments (piano / guitar / violin / synth…). For example: "serene music for meditation, slow synth pads, occasional water drops".
WARNING
Overly simple short music (short duration plus a very brief description) tends to trigger the copyright check — enrich the description or extend the duration.
Song
Generate a song with vocals from an inspiration description (prompt), or provide lyrics for the model to compose and sing.
Example model: volcengine-song. Put the inspiration description in input; lyrics, genre, gender, model version and other upstream parameters are passed through the metadata extension object:
NOTE
In our testing input cannot be empty (returns input is required.). When generating from lyrics, fill input with a short description consistent with the lyrics. Generated lyrics may differ from what you passed in (rewrites / repeats / section completion) — treat actual output as authoritative.
curl https://api-model.shuntianchuang.cn/v1/audio/speech \
-H "Authorization: Bearer sk-your-token" \
-H "Content-Type: application/json" \
-d '{
"model": "volcengine-song",
"input": "一首关于周末午后咖啡店的城市民谣",
"response_format": "wav",
"metadata": {
"duration": 60,
"model_version": "v4.3",
"gender": "Female"
}
}' \
-o song.wav
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/audio/speech",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={
"model": "volcengine-song",
# Chinese prompt works best for the upstream model
"input": "一首关于周末午后咖啡店的城市民谣",
"response_format": "wav",
"metadata": {"duration": 60, "model_version": "v4.3", "gender": "Female"},
},
timeout=120, # song generation is slow; use a generous timeout
)
resp.raise_for_status()
with open("song.wav", "wb") as f:
f.write(resp.content)
import fs from 'node:fs';
// metadata is a vendor extension parameter; use native fetch (Node.js 18+)
const resp = await fetch(
'https://api-model.shuntianchuang.cn/v1/audio/speech',
{
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'volcengine-song',
// Chinese prompt works best for the upstream model
input: '一首关于周末午后咖啡店的城市民谣',
response_format: 'wav',
metadata: { duration: 60, model_version: 'v4.3', gender: 'Female' },
}),
},
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
fs.writeFileSync('song.wav', Buffer.from(await resp.arrayBuffer()));
Generating from lyrics: when metadata.lyrics is non-empty the model follows the lyrics (input is still required but its content does not participate in generation):
curl -X POST https://api-model.shuntianchuang.cn/v1/audio/speech \
-H "Authorization: Bearer sk-your-token" \
-H "Content-Type: application/json" \
-d '{
"model": "volcengine-song",
"input": "pop style",
"response_format": "wav",
"metadata": {
"lyrics": "[verse]\n走在夏日的街头\n微风拂过我的脸\n[chorus]\n这就是夏天的味道\n阳光洒满了整条街",
"duration": 60,
"model_version": "v4.3",
"gender": "Female"
}
}' \
--output song_lyrics.wav