Get Music Generation Task Status

Query the progress and result of a music generation task, used together with Create Music Generation Task (doubao-music-bgm / doubao-music-song). Poll about every 5 seconds until status becomes completed or failed.

WARNING

data.url is a signed temporary URL on the upstream CDN with an expiry — download and transfer it to your own storage promptly; once expired, the task must be resubmitted.

Endpoint

GET /volcengine/music/fetch/{task_id}

Authentication

Pass the Bearer token in the request header:

Authorization: Bearer sk-your-token

Path Parameters

ParameterTypeRequiredNotes
task_idstringYesTask ID returned by the submit endpoint

Response Body

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_t3NzFBs4R4uOhkgaSCdSbKTbOv4o3s1I",
    "status": "completed",
    "url": "https://v9-default.douyinvod.com/....wav?a=7518&...",
    "format": "wav",
    "metadata": { "duration": 30 },
    "error": null
  }
}
data fieldNotes
statusqueued (waiting) / processing (generating) / completed (done) / failed (failed)
urlAudio download URL; non-empty only when completed
formatAlways wav
metadata.durationActual audio duration in seconds as returned by the upstream (billing settles against it)
errorFailure info; non-empty only when failed, e.g. {"code": 1, "message": "..."}

Polling Examples

The complete flow from submission to download (you can also start at step 2 with a task_id you already have):

cURL
Python
Node.js
# 1. Submit
curl -s -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"}}

# 2. Poll (replace <task_id> with the value returned above, about every 5 seconds)
curl -s https://api-model.shuntianchuang.cn/volcengine/music/fetch/<task_id> \
  -H "Authorization: Bearer sk-your-token"
# Once status is completed, data.url is the audio URL

# 3. Download
curl -s -o bgm.wav "<data.url>"

Billing pre-charges the requested duration at submission and settles against metadata.duration (the actual upstream duration) on completion, refunding or charging the difference; failed tasks are not billed and are refunded in full — see Billing on the create page.

Errors

HTTPcodeMeaningWhat to check
404task_not_foundTask ID does not existCheck task_id for typos, or whether the task belongs to another account

For submit-side errors (400 invalid_request) and upstream rejections (502), see Errors on the create page.

FAQ

How often should I poll? Every 5 seconds. Polling faster won't get the result sooner — it only adds request volume.

Can I submit and skip polling? Yes. The task keeps running server-side and is billed on actual usage, but the result URL expires and becomes unretrievable — poll and transfer promptly.

How many times can I query one task? Unlimited.

Can I use the generated audio commercially? That is governed by the upstream terms of service. metadata.skip_copy_check only toggles the copyright check at generation time; it does not grant commercial rights.