StepAudio 3 Music 开发对接

StepAudio 3 Music 开发对接#

本文档说明如何通过 new-api 网关调用 StepFun 的 stepaudio-3-music 音乐模型。调用方只需要使用网关统一的音乐 API，不需要直接处理 StepFun 的任务 ID 或响应格式。

model_params 参数#

model_params 只接受下表字段，不能覆盖 model、prompt、lyrics、instrumental 或 callback_url 等公共字段。数值 0 和布尔值 false 会被保留并发送给上游。

以下组合会被网关拒绝：

• song_audio 与 vocal_audio 同时提供。
• task=music_cover 但缺少 song_audio，或 task=vocal_to_music 但缺少 vocal_audio。
• text_to_music 同时使用参考音频。
• instrumental=true 同时提供歌词，或在改编任务中设置 instrumental。
• disable_caption_rewrite=true 与 lyrics_rewrite=true 同时设置。
• disable_caption_rewrite=true 的文生音乐请求没有提供歌词。

callback_url 可以放在请求顶层，由网关负责验证和保存，不会作为 StepFun 请求字段转发。

提交任务#

接口：POST ${BASE}/v1/music/generations

提交成功后，网关立即返回自己的任务 ID；这是异步接口，不要把它当作 StepFun 原始任务 ID 使用。

文生音乐#

curl -X POST "${BASE}/v1/music/generations" \
  -H "Authorization: Bearer ${KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stepaudio-3-music",
    "prompt": "A warm acoustic folk song about a summer road trip",
    "lyrics": "[Verse]\nThe road is open, the morning is bright",
    "instrumental": false,
    "model_params": {
      "response_format": "mp3",
      "sample_rate": 44100,
      "bit_rate": 192
    }
  }'

纯音乐可以省略 lyrics，但 StepAudio 请求应提供非空 prompt：

{
  "model": "stepaudio-3-music",
  "prompt": "Ambient piano and strings for a quiet night",
  "instrumental": true
}

instrumental: true 时不能同时传 lyrics。可以通过 style 或 tags 提供描述文本。

歌曲改编#

将歌曲音频放在 model_params.song_audio 中，值可以是纯 Base64，也可以是 data:audio/...;base64,... Data URL：

{
  "model": "stepaudio-3-music",
  "prompt": "Keep the chord progression and make the arrangement more cinematic",
  "lyrics": "[Verse]\nA new lyric line",
  "model_params": {
    "task": "music_cover",
    "song_audio": "data:audio/wav;base64,BASE64_AUDIO"
  }
}

music_cover 必须提供 song_audio 和非空 lyrics，不能设置 instrumental。省略 task 时，网关会根据 song_audio 自动选择 music_cover。

人声转音乐#

将人声参考音频放在 model_params.vocal_audio 中：

{
  "model": "stepaudio-3-music",
  "prompt": "Build a full pop arrangement around this vocal",
  "lyrics": "[Chorus]\nWe will meet beneath the summer sky",
  "model_params": {
    "task": "vocal_to_music",
    "vocal_audio": "BASE64_AUDIO"
  }
}

vocal_to_music 必须提供 vocal_audio 和非空 lyrics，不能设置 instrumental。song_audio 和 vocal_audio 不能同时出现。省略 task 时，网关会根据 vocal_audio 自动选择 vocal_to_music。

轮询任务#

提交成功响应：

{
  "code": "success",
  "message": "",
  "data": "task_01KABCDEF0123456789XYZ"
}

查询接口：GET ${BASE}/v1/tasks/:id

curl "${BASE}/v1/tasks/task_01KABCDEF0123456789XYZ" \
  -H "Authorization: Bearer ${KEY}"

任务状态通常经历 queued、in_progress，最终为 completed 或 failed。完成响应中的 data 是统一音乐轨道数组：

{
  "status": "completed",
  "model": "stepaudio-3-music",
  "data": [
    {
      "audio_url": "https://your-gateway.example/media/audio.wav",
      "model_name": "stepaudio-3-music",
      "provider": "stepfun",
      "status": "completed"
    }
  ]
}

客户端应读取 audio_url 播放或下载，并继续轮询直到进入终态。失败任务的 fail_reason 可能来自 StepFun 的错误消息；如果上游没有提供可用音频或网关无法保存音频，会返回任务失败。

错误处理#

• 401：检查网关 API Key。
• 400：检查 prompt、lyrics、任务类型和 model_params 约束。
• 502 或任务进入 failed：检查 StepFun API Key、渠道基础 URL 和上游服务状态。
• 参考音频请求失败：确认 Data URL 的 MIME 类型以 audio/ 开头，并确认 Base64 解码后未超过网关限制。

不要直接调用 StepFun 的 /v1/audio/music/submit 或 /v1/audio/music/query。这两个上游路径由网关适配器内部使用，客户端应始终调用网关统一接口。