• 简体中文
  • 旧版使用指南(同步接口)

    NOTE

    本页面向平台升级前接入、使用同步接口 /v1/audio/speech 生成音乐的存量用户(模型 volcengine-bgm / volcengine-song),存量调用可继续使用;MiniMax Music(chat 流式)见 MiniMax 格式。新项目建议使用新版异步任务接口(doubao-music-bgm / doubao-music-song),支持批量提交与任务队列统一管理。

    volcengine-bgm(文字生成纯音乐)与 volcengine-song(文字生成带人声歌曲)通过同步接口 /v1/audio/speech 调用:请求会一直阻塞到音频生成完毕、直接返回音频二进制。可用模型与最新价格以模型广场为准。

    通用调用结构

    /v1/audio/speech 音乐模型(BGM / Song)共用同一请求骨架:

    curl https://api-model.shuntianchuang.cn/v1/audio/speech \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "<模型名>",
        "input": "<文本 / 描述>",
        "response_format": "<输出格式>"
      }' \
      -o output.<格式>
    字段类型必填说明
    modelstring是模型名,可用音频模型以模型广场为准
    inputstring是文本输入:TTS 为待合成文本,BGM / Song 为音乐描述或灵感提示词
    response_formatstring视模型输出音频格式,可选值与是否必填随模型而异,见各能力小节

    voice(音色)、speed(语速)与 metadata(厂商扩展参数透传对象)为模型专属字段,见各能力小节的「火山引擎格式」。

    响应:成功返回二进制音频流,按所请求格式保存为文件即可(如 -o speech.mp3);失败返回 JSON 错误体,对照错误码说明排查。

    NOTE

    /v1/audio/speech 音频接口调用成功后,响应头会携带计费信息:X-Audio-Duration(音频时长,秒)、X-TTS-Chars(输入字符数)、X-Prompt-Tokens / X-Completion-Tokens / X-Total-Tokens(token 用量)、X-Usage(完整 usage JSON)。MiniMax Speech(chat 端点)的用量直接在响应 JSON 的 usage 字段中。费用明细也可在控制台「使用日志」查看。

    WARNING

    音乐生成类模型(BGM / Song)生成耗时约 30~60 秒,客户端超时建议设到 120 秒以上。

    背景音乐(BGM)

    用一段文字描述生成背景纯音乐,时长等上游参数通过 metadata 扩展对象透传。

    火山引擎格式

    示例模型:volcengine-bgm,描述仅支持中文,可写曲风、心情、场景、乐器等:

    字段类型必填说明
    modelstring是volcengine-bgm
    inputstring是音乐描述(仅中文),可描述曲风、心情、场景、乐器
    response_formatstring是固定传 wav:BGM 原生返回 WAV,显式传入可确保网关按时长正确计费
    metadata.durationint否时长(秒),范围 30~120,默认 60
    metadata.enable_input_rewritebool否是否让 AI 改写提示词,默认 false
    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/v1/audio/speech \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "volcengine-bgm",
        "input": "轻松愉快的背景纯音乐,钢琴伴奏,适合咖啡馆场景",
        "response_format": "wav",
        "metadata": {
          "duration": 60,
          "enable_input_rewrite": false
        }
      }' \
      --output bgm.wav
    NOTE

    BGM 与 Song 实测仅支持 wav 输出:保存文件请用 .wav 后缀;需要 mp3 可自行转码,如 ffmpeg -i bgm.wav bgm.mp3。

    TIP

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

    WARNING

    过于简单的短音乐(时长短且描述很短)容易触发版权校验,建议丰富描述或延长时长。

    歌曲(Song)

    用灵感描述(提示词)生成带人声的歌曲,也可传入歌词由模型谱曲演唱。

    火山引擎格式

    示例模型:volcengine-song。input 填灵感描述;歌词、曲风、性别、模型版本等上游参数通过 metadata 扩展对象透传:

    字段类型必填说明
    modelstring是volcengine-song
    inputstring是歌曲描述(提示词),如「一首关于周末午后咖啡店的城市民谣」;metadata.lyrics 非空时模型优先按歌词生成
    response_formatstring是固定传 wav(原生返回 WAV)
    metadata.durationint否时长(秒),范围 30~120,默认 60
    metadata.lyricsstring否歌词文本,非空时优先使用歌词生成;可用 [verse] / [chorus] 标记段落
    metadata.model_versionstring否模型版本:v4.0 / v4.3 / v5.0,默认 v4.3
    metadata.genderstring否演唱者性别:Female / Male
    metadata.genrestring否曲风:Electronic / Pop / Folk 等
    metadata.moodstring否情绪:Groovy / Happy / Sad 等
    metadata.timbrestring否音色描述
    metadata.skip_copy_checkbool否是否关闭版权检测,默认 false
    NOTE

    本站实测 input 不可置空(返回 input is required.),按歌词生成时建议在 input 中填与歌词内容一致的简短描述;生成歌词与传入歌词可能存在差异(改写 / 重复 / 段落补全),以实际输出为准。

    cURL
    Python
    Node.js
    curl https://api-model.shuntianchuang.cn/v1/audio/speech \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "volcengine-song",
        "input": "一首关于周末午后咖啡店的城市民谣",
        "response_format": "wav",
        "metadata": {
          "duration": 60,
          "model_version": "v4.3",
          "gender": "Female"
        }
      }' \
      -o song.wav

    传入歌词生成:metadata.lyrics 非空时模型以歌词内容为准(input 仍必填,内容不参与生成):

    curl -X POST https://api-model.shuntianchuang.cn/v1/audio/speech \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "volcengine-song",
        "input": "流行风格",
        "response_format": "wav",
        "metadata": {
          "lyrics": "[verse]\n走在夏日的街头\n微风拂过我的脸\n[chorus]\n这就是夏天的味道\n阳光洒满了整条街",
          "duration": 60,
          "model_version": "v4.3",
          "gender": "Female"
        }
      }' \
      --output song_lyrics.wav