添加音轨

  • 在已有音轨上叠加一条 stem（声部），异步任务
  • 与「添加伴奏」不同：这里只加一条特定乐器
  • 生成参数与其他 suno 操作同源
POST/v1/music/generations/addStem

认证

string必填

所有接口均使用 Bearer Token 进行认证。

获取 API Key：访问控制台 创建。

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

引用源音轨

string必填

产出源音轨那次任务的 task_id。缺失或解析不到源任务时提交阶段返回 400。

integer可选

指定源任务结果 data.result.music[] 中的第几首，默认 1，从 1 开始计数。一次生成一般是 2 首。

生成参数

string可选

音频模型，当前只传 suno。

string可选

公共版本，默认 v6，可选 v6-wild、v6-mini。使用 custom_model_id 时应省略。

string可选

创建模型任务返回的完整 UUID，与 version 互斥。

boolean可选

true 为自定义模式，用 prompt 当歌词；false 为灵感模式，用 gpt_description。

不传时按传入内容推断：有 prompt 判 true，仅有 gpt_description 判 false，仅有 tags 或 title 判 true。

string可选

歌词，仅在 custom=true 时生效。

string条件必填

灵感提示词。custom=false 时必填，该模式下缺失会直接 400 且不扣费。

string可选

标题，仅 custom=true 时生效。

string可选

风格标签，仅 custom=true 时生效。这里就是描述要加什么声部的地方，例如 strings, warm。

string可选

需排除的风格标签，仅 custom=true 时生效。

number可选

风格权重，取值 0.00 到 1.00。超范围提交即 400，仅 custom=true 时生效。

number可选

创意权重，取值 0.00 到 1.00。旧名 weirdness_constraint 仍兼容。

number可选

音频权重，取值 0.00 到 1.00，仅 custom=true 时生效。

string可选

风格变化程度，可选 off、normal、high、extra、max。

boolean可选

启用 Max 模式，默认 false。要求自定义模式，按普通价格 2 倍计费。

string可选

输出格式，可选 mp3、m4a、wav。

不支持的字段

auto_lyrics、persona_id、instrumental、vocal_gender、目标时长字段都不支持。

这里连 vocal_gender 都不支持——本接口是加器乐声部，不涉及人声性别。要加人声用「添加人声」接口。

响应

integer

状态码。

data[] 的元素字段 · 2 项
string

提交后为 submitted。

string

任务唯一标识，用于轮询。

取结果

轮询 GET /v1/music/tasks/{task_id}，建议间隔 3 到 5 秒，终止条件是 status 为 completed 或 failed。

通常耗时 30 到 120 秒，中间状态可能是 pending 或 processing。progress 为 0 到 100 的整数，变化节点不固定。

完成后从 data.result.music[] 读取 audio_url。失败原因见 data.error.message，预扣额度会自动退回。

三个「添加」接口的分工

接口加什么用途
添加人声演唱给纯伴奏配唱
添加伴奏整套伴奏给清唱配器
添加音轨（本页）单条声部给成品补弦乐、补和声

错误码

错误响应的格式、状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

提交一个任务并拿到 task_id：

提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。