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>
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.

Background Music (BGM)

Generate instrumental background music from a text description; duration and other upstream parameters are passed through the metadata extension object.

Volcengine Format

Example model: volcengine-bgm. The description supports Chinese only — you can describe genre, mood, scene, instruments, etc.:

FieldTypeRequiredNotes
modelstringYesvolcengine-bgm
inputstringYesMusic description (Chinese only): genre, mood, scene, instruments
response_formatstringYesAlways pass wav: BGM natively returns WAV; passing it explicitly ensures the gateway bills by duration correctly
metadata.durationintNoDuration (seconds), 30–120, defaults to 60
metadata.enable_input_rewriteboolNoLet AI rewrite the prompt; defaults to false
cURL
Python
Node.js
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
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.

Volcengine Format

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:

FieldTypeRequiredNotes
modelstringYesvolcengine-song
inputstringYesSong description (prompt), e.g. "an urban folk song about a coffee shop on a weekend afternoon"; when metadata.lyrics is non-empty the model generates from the lyrics first
response_formatstringYesAlways pass wav (natively returns WAV)
metadata.durationintNoDuration (seconds), 30–120, defaults to 60
metadata.lyricsstringNoLyrics text; when non-empty, lyrics take priority; sections can be marked with [verse] / [chorus]
metadata.model_versionstringNoModel version: v4.0 / v4.3 / v5.0, defaults to v4.3
metadata.genderstringNoVocalist gender: Female / Male
metadata.genrestringNoGenre: Electronic / Pop / Folk, etc.
metadata.moodstringNoMood: Groovy / Happy / Sad, etc.
metadata.timbrestringNoTimbre description
metadata.skip_copy_checkboolNoDisable the copyright check; defaults to false
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
Python
Node.js
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

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