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
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
}
}
Polling Examples
The complete flow from submission to download (you can also start at step 2 with a task_id you already have):
# 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>"
import time
import requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-your-token", "Content-Type": "application/json"}
# 1. Submit (Chinese prompt works best for the upstream model)
resp = requests.post(f"{BASE}/volcengine/music/submit", headers=HEADERS, json={
"model": "doubao-music-bgm",
"input": "轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景",
"metadata": {"duration": 30},
}, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["task_id"]
print("task_id:", task_id)
# 2. Poll (a 30-second track took about 17 seconds in our tests; wait up to 5 minutes here)
audio_url = ""
for _ in range(60):
time.sleep(5)
task = requests.get(f"{BASE}/volcengine/music/fetch/{task_id}",
headers=HEADERS, timeout=30).json()["data"]
print(task["status"])
if task["status"] == "completed":
audio_url = task["url"]
break
if task["status"] == "failed":
raise RuntimeError(task.get("error"))
# 3. Download (signed temporary URL — transfer to your own storage promptly)
with open("bgm.wav", "wb") as f:
f.write(requests.get(audio_url, timeout=120).content)
import fs from 'node:fs';
const BASE = 'https://api-model.shuntianchuang.cn';
const HEADERS = {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
};
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// 1. Submit (Chinese prompt works best for the upstream model)
const submitted = await (
await fetch(`${BASE}/volcengine/music/submit`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'doubao-music-bgm',
input: '轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景',
metadata: { duration: 30 },
}),
})
).json();
const taskId = submitted.data.task_id;
console.log('task_id:', taskId);
// 2. Poll (a 30-second track took about 17 seconds in our tests; wait up to 5 minutes here)
let audioUrl = '';
for (let i = 0; i < 60; i++) {
await sleep(5000);
const task = (
await (
await fetch(`${BASE}/volcengine/music/fetch/${taskId}`, {
headers: HEADERS,
})
).json()
).data;
console.log(task.status);
if (task.status === 'completed') {
audioUrl = task.url;
break;
}
if (task.status === 'failed') throw new Error(JSON.stringify(task.error));
}
// 3. Download (signed temporary URL — transfer to your own storage promptly)
const audio = await fetch(audioUrl);
fs.writeFileSync('bgm.wav', Buffer.from(await audio.arrayBuffer()));
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
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.