• 简体中文
  • 创建音乐生成任务

    音乐生成支持异步任务:提交任务 → 轮询状态 → 获取结果。提交后立即返回任务 ID,不占用连接,适合批量提交、长时间生成、以及在任务队列里统一管理的场景。可用模型与最新价格以模型广场为准。

    模型说明
    doubao-music-bgm纯音乐(背景音乐),由文字描述生成
    doubao-music-song带人声的歌曲,可传歌词或由模型自动谱曲
    TIP

    音乐生成还支持 MiniMax 格式(/v1/chat/completions chat 流式生成歌曲,无需轮询);升级前提供的同步接口 /v1/audio/speech(volcengine-bgm / volcengine-song)见旧版使用指南,存量用户可继续使用。同步接口会一直阻塞到音频生成完毕、直接返回音频二进制,而本页异步接口先返回任务 ID,客户端自行轮询。

    NOTE

    异步任务在提交时即按申请时长预扣费,任务完成时按上游实际返回的时长结算,多退少补。可随时在控制台「使用日志」核对。

    WARNING

    生成耗时通常 15~60 秒(实测 30 秒的曲子约 17 秒完成),但高峰期或长时长可能更久。轮询建议预留 5 分钟以上,单次轮询请求超时设 30 秒即可,见获取音乐生成任务状态。

    端点

    POST /volcengine/music/submit

    认证

    请求头携带 Bearer 令牌(令牌获取见接入地址与鉴权):

    Authorization: Bearer sk-你的令牌

    请求体

    字段类型必填说明
    modelstring是doubao-music-bgm(纯音乐)或 doubao-music-song(歌曲)
    inputstring见下音乐描述 / 灵感提示词。Song 在未传 metadata.lyrics 时必填
    metadataobject否扩展参数对象,逐字段透传上游,见下方 metadata 参数详解

    metadata 参数详解

    以下参数全部通过 metadata 对象透传,不传即使用默认值。

    BGM(doubao-music-bgm):

    字段类型默认说明
    metadata.durationint60时长(秒),范围 30~120
    metadata.versionstringv5.0模型版本
    metadata.enable_input_rewriteboolfalse是否让模型改写提示词

    Song(doubao-music-song):

    字段类型默认说明
    metadata.durationint60时长(秒),范围 30~240
    metadata.model_versionstringv4.3模型版本,可选 v4.0 / v4.3 / v5.0
    metadata.lyricsstring空歌词文本,非空时优先按歌词生成(此时 input 可省略);可用 [verse] / [chorus] 标记段落
    metadata.genderstring空演唱者性别:Female / Male
    metadata.genrestring空曲风,必须从下方枚举中选
    metadata.moodstring空情绪,必须从下方枚举中选
    metadata.timbrestring空音色,必须从下方英文枚举中选
    metadata.skip_copy_checkboolfalse是否关闭版权检测
    WARNING

    genre / mood / timbre 三个参数由上游做严格枚举校验,不接受除此之外的任何值。传了非枚举值会返回 HTTP 502 并在错误信息中列出全部合法值。input 也有约束:词数须在 5~2000 之间(过短会被拒绝)。

    曲风 genre 可选值

    必须使用下列英文原值,大小写敏感(传 pop 会报错,必须传 Pop):

    Pop, Jazz, Rock, Classical, Country, Folk, Electronic, EDM, House,
    Hip Hop/Rap, R&B/Soul, Blues, Punk, Metal, Reggae, DJ, MC,
    Chinese Style, Chinese Pop, Chinese Tradition, Chinese Folk, Chinese Ballad Pop,
    GuFeng Music, Chinese Opera, China-Wave, Chinoiserie Rock, Traditional Chinese Folk,
    Alternative/Indie, Indie Pop, Dream Pop, City Pop, Synth Pop, Dance Pop,
    Ambient, Chillout, Trance, Disco, Vaporwave, Trip Hop, Downtempo, Breakbeat,
    Bossa Nova, Swing, Big Band, Cool Jazz, Jazz Pop, Soul, Funk, Neo Soul, Gospel,
    Hard Rock, Pop Rock, Alternative Rock, Indie Rock, Soft Rock, Country Rock,
    Trap Rap, Pop Rap, Emo Rap, Gangsta Rap, Jazz Hip Hop, Chill Beats, Boombap

    以上为常用值节选。完整列表(约 100 项)会在参数错误时随报错一并返回,可据此核对。

    情绪 mood 可选值

    Happy, Calm/Relaxing, Chill, Cute/Playful, Dynamic/Energetic, Excited, Funny,
    Healing, Inspirational/Hopeful, Sentimental/Melancholic/Lonely, Miss, Mysterious,
    Romantic, Sorrow/Sad, Sweet_SA_MOOD, Thrilling/Suspenseful/Tense, Weird,
    Groovy/Funky, Nostalgic/Memory, Dreamy/Ethereal, Magnificent/Epic, Brisk/Carefree,
    Warm/Kind, Confident/Determined, Lyrical/Ballad

    音色 timbre 可选值

    必须使用英文原值(传 女声 会报错):

    Warm, Ethereal, Husky, Deep, Extreme, Sharp, Bright, Powerful, Sexy/Lazy, Magnetic,
    Bel Canto, Gentle, Delicate, Energetic, Sassy, Refreshing, Soothing, Comical,
    Uncle Like, Gritty, Romantic_AUDIO_TIMBRE, Enthusiastic, Smoky, Chinese Opera Tune,
    Round, Flat, Growling
    TIP

    描述越丰富效果越好。可从四个维度组织:曲风(流行 / 古典 / 爵士 / 电子…)、心情(轻松 / 忧伤 / 激昂 / 宁静…)、场景(咖啡馆 / 婚礼 / 运动 / 冥想…)、乐器(钢琴 / 吉他 / 小提琴 / 合成器…)。例如「冥想用的宁静音乐,缓慢的合成器铺底,偶尔有水滴声」。

    请求示例

    cURL
    Python
    Node.js
    # 场景 1:BGM(纯音乐)
    curl -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:Song 传歌词(传了 metadata.lyrics 后 input 可省略)
    curl -X POST https://api-model.shuntianchuang.cn/volcengine/music/submit \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-music-song",
        "metadata": {
          "lyrics": "[verse]走在夏日的街头\n微风拂过我的脸\n[chorus]这就是夏天的味道\n阳光洒满了整条街",
          "duration": 30
        }
      }'
    NOTE

    传了 metadata.lyrics 之后 input 可以省略(实测通过);两者都传时以歌词为准。

    响应体

    提交成功立即返回任务 ID,status 固定为 queued(已入队):

    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_t3NzFBs4R4uOhkgaSCdSbKTbOv4o3s1I",
        "status": "queued"
      }
    }
    字段说明
    data.task_id任务 ID,后续轮询用
    data.status固定为 queued(已入队)

    计费

    按音频时长计费,与提示词长度基本无关。

    • 提交时按申请时长预扣费;
    • 完成时按上游返回的实际时长结算,多退少补(上游返回的时长可能与申请值差 1 秒,退款会自动产生);
    • 任务失败不计费,预扣费全额退回。

    计费明细(时长、字符数、扣费金额)可在控制台 → 使用日志中查询,每条任务对应一条 doubao-music-bgm / doubao-music-song 的消费记录。

    错误码与排查

    HTTPcode含义排查方向
    400invalid_request请求参数不合法看 message,通常是模型名不对、input 缺失、duration 越界或 metadata 类型错误
    502server_error上游拒绝了请求常见于 genre / mood / timbre 传了非枚举值,或 input 词数不合规

    常见 400 报错原文与含义:

    报错原文原因
    input is required.Song 未传 input 且未传 metadata.lyrics
    metadata.duration must be between 30 and 120 seconds for doubao-music-bgm.BGM 时长越界
    metadata.duration must be between 30 and 240 seconds for doubao-music-song.Song 时长越界
    metadata must be an object.metadata 传成了字符串 / 数组
    model "xxx" is not allowed on this route.model 不是本接口支持的模型
    NOTE

    上游的详细报错只记录在服务端日志中,接口对外统一返回 502 Task request failed。若排查困难,可把任务提交时间与令牌名提供给我们,我们可协助查询服务端日志。

    提交成功后轮询任务状态并下载音频,见获取音乐生成任务状态。