• 简体中文
  • 获取音乐生成任务状态

    查询音乐生成任务的进度与结果,与创建音乐生成任务(doubao-music-bgm / doubao-music-song)配套使用。建议每 5 秒轮询一次,直到 status 变为 completed 或 failed。

    WARNING

    data.url 为上游 CDN 的带签名临时地址,有时效,请及时下载转存到自己的存储;过期后需重新发起任务。

    端点

    GET /volcengine/music/fetch/{task_id}

    认证

    请求头携带 Bearer 令牌:

    Authorization: Bearer sk-你的令牌

    路径参数

    参数类型必填说明
    task_idstring是提交接口返回的任务 ID

    响应体

    {
      "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 字段说明
    statusqueued 排队中 / processing 生成中 / completed 已完成 / failed 已失败
    url音频下载地址,仅在 completed 时非空
    format固定 wav
    metadata.duration音频时长(秒),上游返回的实际值(计费按它结算,多退少补)
    error失败信息,仅在 failed 时非空,形如 {"code": 1, "message": "..."}

    轮询示例

    从提交到下载的完整流程(也可从第 2 步开始,换成你已有的 task_id):

    cURL
    Python
    Node.js
    # 1. 提交
    curl -s -X POST https://api-model.shuntianchuang.cn/volcengine/music/submit \
      -H "Authorization: Bearer sk-你的令牌" \
      -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. 轮询(把 <task_id> 换成上一步的返回值,建议每 5 秒一次)
    curl -s https://api-model.shuntianchuang.cn/volcengine/music/fetch/<task_id> \
      -H "Authorization: Bearer sk-你的令牌"
    # status 为 completed 后,data.url 即音频地址
    
    # 3. 下载
    curl -s -o bgm.wav "<data.url 的地址>"

    计费在提交时按申请时长预扣费,完成时按 metadata.duration(上游实际时长)结算,多退少补;任务失败不计费、全额退回,详见创建音乐生成任务。

    错误码

    HTTPcode含义排查方向
    404task_not_found任务 ID 不存在检查 task_id 是否拼错,或是否用了别的账号的任务

    提交侧的参数错误(400 invalid_request)与上游拒绝(502)见创建音乐生成任务的错误码。

    常见问题

    轮询要多久一次? 建议 5 秒。频次过高不会更快拿到结果,只会增加请求量。

    可以提交后不轮询吗? 可以。任务会在服务端继续执行并按实际用量计费,但结果地址有时效,过期后无法再取,建议及时轮询并转存。

    同一个任务能查几次? 不限次数。

    生成的音频能商用吗? 由上游的服务条款约束;metadata.skip_copy_check 仅控制生成时的版权检测开关,不代表授权商用。