淡入

  • 为已有音轨添加开头淡入效果，异步任务
  • 用 duration_s 控制淡入时长
  • 淡入失败通常是时长超过了源音频长度
POST/v1/music/generations/fadeIn

认证

string必填

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

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

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

引用源音轨

string必填

产出源音轨的那次任务的标识。缺失或无法解析出源音轨时，提交阶段立即返回 400。

integer可选

从源任务结果的 data.result.music[] 中选取要处理的曲目，默认 1，从 1 起始。一次生成通常产出 2 首。

基于已有歌曲操作时，只需 task_id 与 audio_index 两个值，无需另外记录任何 ID。

请求参数

string可选

音频模型，省略时默认为 suno，当前仅此一个取值。

number必填

淡入时长，单位秒。须大于 0 且不超过源音轨的已知时长，允许小数秒。

string可选

处理后音轨的标题，默认 Untitled。

关于 duration_s 的上限

上限取决于源音轨有多长，而源音轨的时长在提交前无法得知。所以想稳妥一点，先查一次源任务拿 duration_seconds，再决定淡入时长。

一般的经验值：淡入取源曲长的 3% 到 8%。3 分钟的歌就是 5 到 14 秒。

本端点没有版本参数。传 version 会被忽略，也不影响计费。

响应

integer

响应状态码。

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

任务状态，提交成功为 submitted。

string

任务唯一标识，轮询时使用。

取结果

用 GET /v1/music/tasks/{task_id} 轮询，间隔 3 到 5 秒，典型耗时 30 到 120 秒。

status 的中间态为 pending、processing，终态为 completed 或 failed。progress 是 0 到 100 的整数，不保证按固定节点变化。

完成后从 data.result.music[] 每一项的 audio_url 取音频。失败时 data.error.message 给出原因，预扣额度自动退回。

错误码

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

使用示例

提交一个任务并拿到 task_id：

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