创建音乐生成任务
音乐生成支持异步任务:提交任务 → 轮询状态 → 获取结果。提交后立即返回任务 ID,不占用连接,适合批量提交、长时间生成、以及在任务队列里统一管理的场景。可用模型与最新价格以模型广场为准。
音乐生成还支持 MiniMax 格式(/v1/chat/completions chat 流式生成歌曲,无需轮询);升级前提供的同步接口 /v1/audio/speech(volcengine-bgm / volcengine-song)见旧版使用指南,存量用户可继续使用。同步接口会一直阻塞到音频生成完毕、直接返回音频二进制,而本页异步接口先返回任务 ID,客户端自行轮询。
异步任务在提交时即按申请时长预扣费,任务完成时按上游实际返回的时长结算,多退少补。可随时在控制台「使用日志」核对。
生成耗时通常 15~60 秒(实测 30 秒的曲子约 17 秒完成),但高峰期或长时长可能更久。轮询建议预留 5 分钟以上,单次轮询请求超时设 30 秒即可,见获取音乐生成任务状态。
端点
POST /volcengine/music/submit
认证
请求头携带 Bearer 令牌(令牌获取见接入地址与鉴权):
请求体
metadata 参数详解
以下参数全部通过 metadata 对象透传,不传即使用默认值。
BGM(doubao-music-bgm):
Song(doubao-music-song):
genre / mood / timbre 三个参数由上游做严格枚举校验,不接受除此之外的任何值。传了非枚举值会返回 HTTP 502 并在错误信息中列出全部合法值。input 也有约束:词数须在 5~2000 之间(过短会被拒绝)。
曲风 genre 可选值
必须使用下列英文原值,大小写敏感(传 pop 会报错,必须传 Pop):
以上为常用值节选。完整列表(约 100 项)会在参数错误时随报错一并返回,可据此核对。
情绪 mood 可选值
音色 timbre 可选值
必须使用英文原值(传 女声 会报错):
描述越丰富效果越好。可从四个维度组织:曲风(流行 / 古典 / 爵士 / 电子…)、心情(轻松 / 忧伤 / 激昂 / 宁静…)、场景(咖啡馆 / 婚礼 / 运动 / 冥想…)、乐器(钢琴 / 吉他 / 小提琴 / 合成器…)。例如「冥想用的宁静音乐,缓慢的合成器铺底,偶尔有水滴声」。
请求示例
传了 metadata.lyrics 之后 input 可以省略(实测通过);两者都传时以歌词为准。
响应体
提交成功立即返回任务 ID,status 固定为 queued(已入队):
计费
按音频时长计费,与提示词长度基本无关。
- 提交时按申请时长预扣费;
- 完成时按上游返回的实际时长结算,多退少补(上游返回的时长可能与申请值差 1 秒,退款会自动产生);
- 任务失败不计费,预扣费全额退回。
计费明细(时长、字符数、扣费金额)可在控制台 → 使用日志中查询,每条任务对应一条 doubao-music-bgm / doubao-music-song 的消费记录。
错误码与排查
常见 400 报错原文与含义:
上游的详细报错只记录在服务端日志中,接口对外统一返回 502 Task request failed。若排查困难,可把任务提交时间与令牌名提供给我们,我们可协助查询服务端日志。
提交成功后轮询任务状态并下载音频,见获取音乐生成任务状态。
