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.
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.
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.
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):
Request Body
metadata Reference
All parameters below are passed through the metadata object. Omitting a field uses its default.
BGM (doubao-music-bgm):
Song (doubao-music-song):
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):
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
Timbre (timbre) Values
Use the English values exactly as listed (passing 女声 — "female voice" — fails):
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
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:
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
Common 400 error messages and their causes:
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.
