• 简体中文
  • MiniMax 格式(MiniMax Music)

    通过 POST /v1/chat/completions 以 SSE 流式生成歌曲,可用模型 minimax-music-v2.6 / minimax-music-v3.0(独立定价,以模型广场为准)。生成期间每 15 秒推送一个心跳块保持连接,出歌后推送音频下载地址——无需提交任务和轮询,也不存在「生成超时被掐断、扣费拿不到结果」的问题。

    TIP

    音乐生成另支持火山引擎格式:异步任务接口(doubao-music-bgm / doubao-music-song,提交 → 轮询 → 下载)与升级前的同步接口(旧版使用指南),按模型与接入方式选择。

    调用流程

    1. 发起请求:POST /v1/chat/completions,stream: true 必须开启,业务参数放 metadata 对象;
    2. 读取流:生成期间(约 40~341 秒,纯音乐较长)每 15 秒收到一个空内容心跳块;出歌后某个块的 delta.content 即歌曲 mp3 地址;
    3. 下载音频:访问该 URL 保存文件,地址 12 小时有效,请及时转存。
    WARNING

    stream 必须为 true,且请求必须带 messages 数组。客户端超时建议 ≥600 秒。

    请求参数

    字段类型必填说明
    modelstring是minimax-music-v2.6 / minimax-music-v3.0
    streambool是固定传 true;非流式请求会被拒绝
    messagesarray是对话消息数组;metadata 未传 prompt 时,自动回退用最后一条 user 消息作风格描述
    metadata.promptstring见下风格描述:曲风 / 心情 / 场景 / 乐器,如「独立民谣,忧郁,内省,咖啡馆。长度限制 [0, 2000] 字符;生成纯音乐(is_instrumental: true)时必填,长度限制 [1, 2000] 字符。」
    metadata.lyricsstring见下自定义歌词,支持 [verse] / [chorus] 段落标记;非空时按歌词谱曲演唱
    metadata.lyrics_optimizerbool否是否根据 prompt 描述自动生成歌词。设为 true 且 lyrics 为空时,系统按 prompt 自动写词。默认值:false。
    metadata.is_instrumentalbool否true 生成纯音乐(无人声),此时必须传 prompt
    metadata.audio_settingobject否音频参数,如 {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}
    metadata.aigc_watermarkbool否是否在音频末尾加水印,默认 false。注意:实测开启后上游会将音频强制转码为 128kbps,覆盖 audio_setting.bitrate,需要高音质请勿开启

    prompt / lyrics / is_instrumental 至少传一个,三种用法:

    • 自定义歌词:lyrics(必填)+ prompt(可选风格描述)
    • 自动写词:lyrics_optimizer: true + prompt(歌曲主题),不传 lyrics
    • 纯音乐:is_instrumental: true + prompt(必填),无需 lyrics

    调用示例

    cURL
    Python (openai)
    Node.js (openai)
    curl -N https://api-model.shuntianchuang.cn/v1/chat/completions \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "minimax-music-v3.0",
        "stream": true,
        "messages": [{"role": "user", "content": "舒缓的钢琴曲, 适合专注学习"}],
        "metadata": {
          "prompt": "舒缓的钢琴曲, 适合专注学习, 平静放松",
          "is_instrumental": true
        }
      }'

    流式响应节选(心跳块已省略):

    data: {"choices":[{"delta":{"role":"assistant","content":""}}],...}
    data: {"choices":[{"delta":{"content":"https://...mp3?签名参数"}}],...}   ← 歌曲 mp3 地址
    data: {"choices":[{"delta":{},"finish_reason":"stop"}],...}
    data: {"choices":[],"usage":{"prompt_tokens":100000,"total_tokens":100000}}  ← 计费用量
    data: [DONE]

    计费与错误

    • 计费:流式末块 usage.prompt_tokens 即本次用量(100000/首),按模型倍率计价,可在控制台「使用日志」核对。
    • 失败:上游业务错误以 delta.content 文本(生成失败(未计费): ...)快速送达并基本不计费,不会出现「扣了费拿不到结果」。
    • 音频地址 12 小时有效,请及时下载转存。

    附:Suno 任务格式(已停用)

    WARNING

    Suno 任务格式已于 2026-09-21 停用:/suno/* 端点已下线,调用将返回 404。请改用上文「MiniMax Music(chat 流式)」或火山引擎格式的新版异步任务。以下内容仅作历史参考。

    异步任务协议(Suno 格式):提交后立即返回任务 ID,客户端轮询任务状态直至出歌。适合需要在任务队列中批量提交、轮询管理的场景;当前可用模型 minimax-music-2.0(MiniMax Music 2.0,按首计费,以模型广场为准)。

    调用流程

    1. 提交任务:POST /suno/submit/music,返回任务 ID;
    2. 轮询任务:GET /suno/fetch/{task_id}(单个)或 POST /suno/fetch(批量,body 传 {"ids": [...]}),直至 status 变为 SUCCESS / FAIL;
    3. 下载音频:任务对象的 data[].audio_url 即歌曲 mp3 地址(7 天有效,请及时转存)。

    提交参数

    字段类型必填说明
    mvstring是模型名,当前 minimax-music-2.0。必须显式传,缺省会被补成 Suno 默认值导致「不支持的模型」报错
    gpt_description_promptstring二选一灵感模式:风格描述(曲风 / 心情 / 场景 / 乐器),模型自动写词
    promptstring二选一自定义模式:歌词内容,按歌词谱曲演唱
    tagsstring建议填写自定义模式:曲风 / 风格描述(如「欢快的民谣」)
    make_instrumentalbool否true 生成纯音乐(无人声),默认 false
    title / notify_hook--暂不支持,传入会被忽略
    task_id / continue_at / continue_clip_id--续写暂不支持,传入会返回错误

    gpt_description_prompt(灵感模式)与 prompt(自定义模式歌词)至少填一个;两者都填时按「歌词 + 风格」生成。

    提交响应:{"code":"success","message":"","data":"<任务ID>"};失败返回 {"code":"fail","message":"错误原因"}。

    任务对象

    字段说明
    statusIN_PROGRESS(生成中)/ SUCCESS(成功)/ FAIL(失败)
    progress进度百分比,如 "40%"
    fail_reason失败原因(仅 FAIL 时)
    submit_time / start_time / finish_time提交 / 开始 / 完成的 Unix 时间戳(秒)
    data[].audio_url歌曲 mp3 下载地址(SUCCESS 时)
    data[].metadata.duration歌曲时长(秒)
    data[].metadata.tags / metadata.prompt回显的风格描述 / 歌词
    cURL
    Python
    Node.js
    # 1. 提交(灵感模式:只给风格描述,模型自动写词)
    curl -s https://api-model.shuntianchuang.cn/suno/submit/music \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{"mv": "minimax-music-2.0", "gpt_description_prompt": "欢快的电子舞曲"}'
    # => {"code":"success","message":"","data":"<任务ID>"}
    
    # 2. 轮询(把 <任务ID> 换成上一步返回值,约每 10 秒一次)
    curl -s https://api-model.shuntianchuang.cn/suno/fetch/<任务ID> \
      -H "Authorization: Bearer sk-你的令牌"
    # status 为 SUCCESS 后,data[0].audio_url 即歌曲地址
    
    # 3. 下载
    curl -s -o song.mp3 "<data[0].audio_url 的地址>"

    自定义模式(传歌词 + 风格)的提交 body 示例:

    curl -s https://api-model.shuntianchuang.cn/suno/submit/music \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{"mv": "minimax-music-2.0", "prompt": "大海啊全是水", "tags": "欢快的民谣"}'
    WARNING

    mv 必须显式传 minimax-music-2.0:该协议缺省模型名会被网关补成 Suno 默认值(chirp-v3-0),本站不支持该模型,会返回「不支持的模型」错误。

    NOTE

    生成按首计费,与歌曲时长无关(实测自动写词约 3 分钟整歌与短歌词小样同价);生成耗时 1~5 分钟属正常,轮询间隔建议 10 秒、总等待预留 5 分钟以上。歌曲 mp3 地址 7 天有效,商用场景请及时转存到自己的存储。