Create Music Generation Task

Music generation supports async tasks: submit → poll → fetch the result. Submitting returns a task ID immediately without holding the connection open — ideal for batch submission, long-running generation, and centralized management in a task queue. Available models and current prices are subject to the Model Plaza.

ModelNotes
doubao-music-bgmInstrumental background music generated from a text description
doubao-music-songVocal song; accepts custom lyrics or composes them automatically
TIP

Music generation is also available in the MiniMax Format (/v1/chat/completions chat streaming, no polling needed). The pre-upgrade synchronous /v1/audio/speech endpoint (volcengine-bgm / volcengine-song) is documented in the Legacy Guide — existing users can keep using it. The synchronous endpoint blocks until the audio is fully generated and returns the binary directly, while the async API on this page returns a task ID first and the client polls for the result.

NOTE

An async task is pre-charged based on the requested duration at submission, then settled against the duration actually returned by the upstream when the task completes, with the difference refunded or charged. Check the console's "Usage Logs" at any time.

WARNING

Generation usually takes 15–60 seconds (a 30-second track took about 17 seconds in our tests), but peak hours or long durations can take longer. Allow at least 5 minutes of polling, with a 30-second timeout per poll request. See Get Music Generation Task Status.

Endpoint

POST /volcengine/music/submit

Authentication

Pass the Bearer token in the request header (see Base URL & Authentication):

Authorization: Bearer sk-your-token

Request Body

FieldTypeRequiredNotes
modelstringYesdoubao-music-bgm (instrumental) or doubao-music-song (song)
inputstringSee belowMusic description / inspiration prompt; required for Song when metadata.lyrics is absent
metadataobjectNoExtension object passed through to the upstream field by field — see metadata Reference below

metadata Reference

All parameters below are passed through the metadata object. Omitting a field uses its default.

BGM (doubao-music-bgm):

FieldTypeDefaultNotes
metadata.durationint60Duration (seconds), range 30–120
metadata.versionstringv5.0Model version
metadata.enable_input_rewriteboolfalseLet the model rewrite the prompt

Song (doubao-music-song):

FieldTypeDefaultNotes
metadata.durationint60Duration (seconds), range 30–240
metadata.model_versionstringv4.3Model version: v4.0 / v4.3 / v5.0
metadata.lyricsstringemptyLyrics text; when non-empty the song is generated from the lyrics (input may then be omitted); sections can be marked with [verse] / [chorus]
metadata.genderstringemptyVocalist gender: Female / Male
metadata.genrestringemptyGenre, must be chosen from the enum below
metadata.moodstringemptyMood, must be chosen from the enum below
metadata.timbrestringemptyTimbre, must be chosen from the English enum below
metadata.skip_copy_checkboolfalseDisable the copyright check
WARNING

genre / mood / timbre are strictly validated against the upstream enum — no other values are accepted. A non-enum value returns HTTP 502 with the full list of legal values in the error message. input is also constrained: it must be 5–2000 words (too short is rejected).

Genre (genre) Values

Use the English values exactly as listed — case-sensitive (pop fails; it must be Pop):

Pop, Jazz, Rock, Classical, Country, Folk, Electronic, EDM, House,
Hip Hop/Rap, R&B/Soul, Blues, Punk, Metal, Reggae, DJ, MC,
Chinese Style, Chinese Pop, Chinese Tradition, Chinese Folk, Chinese Ballad Pop,
GuFeng Music, Chinese Opera, China-Wave, Chinoiserie Rock, Traditional Chinese Folk,
Alternative/Indie, Indie Pop, Dream Pop, City Pop, Synth Pop, Dance Pop,
Ambient, Chillout, Trance, Disco, Vaporwave, Trip Hop, Downtempo, Breakbeat,
Bossa Nova, Swing, Big Band, Cool Jazz, Jazz Pop, Soul, Funk, Neo Soul, Gospel,
Hard Rock, Pop Rock, Alternative Rock, Indie Rock, Soft Rock, Country Rock,
Trap Rap, Pop Rap, Emo Rap, Gangsta Rap, Jazz Hip Hop, Chill Beats, Boombap

The above is a selection of common values. The full list (about 100 entries) is returned with the error message when a parameter is invalid — use it to double-check.

Mood (mood) Values

Happy, Calm/Relaxing, Chill, Cute/Playful, Dynamic/Energetic, Excited, Funny,
Healing, Inspirational/Hopeful, Sentimental/Melancholic/Lonely, Miss, Mysterious,
Romantic, Sorrow/Sad, Sweet_SA_MOOD, Thrilling/Suspenseful/Tense, Weird,
Groovy/Funky, Nostalgic/Memory, Dreamy/Ethereal, Magnificent/Epic, Brisk/Carefree,
Warm/Kind, Confident/Determined, Lyrical/Ballad

Timbre (timbre) Values

Use the English values exactly as listed (passing 女声 — "female voice" — fails):

Warm, Ethereal, Husky, Deep, Extreme, Sharp, Bright, Powerful, Sexy/Lazy, Magnetic,
Bel Canto, Gentle, Delicate, Energetic, Sassy, Refreshing, Soothing, Comical,
Uncle Like, Gritty, Romantic_AUDIO_TIMBRE, Enthusiastic, Smoky, Chinese Opera Tune,
Round, Flat, Growling
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…). Chinese descriptions work best for the upstream model.

Request Examples

cURL
Python
Node.js
# Scenario 1: BGM (instrumental)
curl -X POST https://api-model.shuntianchuang.cn/volcengine/music/submit \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-music-bgm",
    "input": "轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景",
    "metadata": { "duration": 30 }
  }'
# => {"code":"success","message":"","data":{"task_id":"task_xxxx","status":"queued"}}
# Scenario 2: Song with lyrics (input may be omitted when metadata.lyrics is present)
curl -X POST https://api-model.shuntianchuang.cn/volcengine/music/submit \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-music-song",
    "metadata": {
      "lyrics": "[verse]走在夏日的街头\n微风拂过我的脸\n[chorus]这就是夏天的味道\n阳光洒满了整条街",
      "duration": 30
    }
  }'
NOTE

Once metadata.lyrics is provided, input may be omitted (verified in testing); when both are passed, the lyrics take precedence.

Response Body

A successful submission returns the task ID immediately, with status fixed at queued:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_t3NzFBs4R4uOhkgaSCdSbKTbOv4o3s1I",
    "status": "queued"
  }
}
FieldNotes
data.task_idTask ID, used for polling
data.statusAlways queued (task enqueued)

Billing

Billed by audio duration, largely independent of prompt length.

  • The requested duration is pre-charged at submission;
  • On completion, billing is settled against the actual duration returned by the upstream, with the difference refunded or charged (the returned duration may differ from the request by about a second — refunds happen automatically);
  • Failed tasks are not billed; the pre-charge is refunded in full.

Billing details (duration, character counts, charges) are available under Console → Usage Logs, with one doubao-music-bgm / doubao-music-song consumption record per task.

Errors & Troubleshooting

HTTPcodeMeaningWhat to check
400invalid_requestInvalid request parametersSee message — usually a wrong model name, missing input, out-of-range duration, or wrong metadata type
502server_errorUpstream rejected requestCommonly a non-enum genre / mood / timbre, or an invalid input word count

Common 400 error messages and their causes:

Error messageCause
input is required.Song submitted with neither input nor metadata.lyrics
metadata.duration must be between 30 and 120 seconds for doubao-music-bgm.BGM duration out of range
metadata.duration must be between 30 and 240 seconds for doubao-music-song.Song duration out of range
metadata must be an object.metadata passed as a string / array
model "xxx" is not allowed on this route.model is not supported on this endpoint
NOTE

Detailed upstream errors are only recorded in server-side logs; the endpoint returns a uniform 502 Task request failed. If troubleshooting stalls, send us the task submission time and token name, and we can check the server logs for you.

After a successful submission, poll the task status and download the audio — see Get Music Generation Task Status.