分轨（人声伴奏分离）API

更新于 2026-09-15 · Suno-API 团队

开发者指南： 两轨与十二轨怎么选、轨道查询和 MIDI 导出

接口说明

分轨用于把已有歌曲拆分为人声、伴奏或多轨结果。推荐按以下流程接入：

1. 如果源音频不是本平台生成的歌曲，可先调用 上传源音频 API。
2. 调用 POST /api/music/separate 提交分轨任务。
3. 使用 歌曲查询 API 轮询分轨结果。
4. 使用下载接口下载每条分轨结果的音频文件。

接口地址: POST /api/music/separate

计费: 收费。stem_mode=two 当前生产价格 1.2 元/次；stem_mode=twelve 为多轨拆分，当前生产价格 3.0 元/次。实际扣费以后台价格配置为准。

等待时间与超时（重要）：本接口是同步接口，响应返回时才代表订单已被受理并提交生成。实测多数请求 1–3 秒返回，约 10% 超过 30 秒，最长约 230 秒。请把客户端超时设置为 300 秒以上；未收到响应不等于没有生成，超时后请勿立即重试（会重复下单、重复扣费）。 连接中断可稍后用 GET /api/music/songs 确认。详见新版 API 总览的「等待时间与超时设置」。

认证

请求参数

stem_mode 说明

分轨说明

分轨是独立的固定能力，不需要填写或选择歌曲生成模型。客户只需提交源歌曲和 stem_mode；服务端会按分轨模式处理。model 字段仅为兼容保留，可以不传。

条数怎么来的：一次提交会产出 2 个版本（同一批素材的两种结果），所以条数 = 2 × 该模式的轨道数：two 是 4 条，twelve 是 24 条。 请以响应里 clips 数组的实际长度为准，不要按固定条数写死循环（个别轨道可能失败，成功的轨道照常返回）。

各模式返回哪些轨道

twelve 模式的 12 条轨道（名称由平台固定给出，顺序可能变化）：

two 模式返回 (Vocals) 与 (Instrumental) 两条轨道，各 2 个版本。 two / twelve 的轨道标题都是固定名（不带来源歌曲名），别指望从标题里看出是哪首歌。

轨道标题不能当唯一键。 两个版本里会出现同名轨道（例如两条 (Vocals)、两条 (Strings)）， 而且一次分轨会返回多条轨道。请一律用 song_id 作为标识，song_title 只用于展示； 也不要用数组下标（顺序可能变化）。

请求示例

人声 / 伴奏分离（stem_mode: "two"）

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

多轨拆分（stem_mode: "twelve"）

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

响应结果

成功后通常会返回分轨结果数组。每个分轨结果都是一个独立歌曲 clip，需要继续查询直到 status 变为完成状态。

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

上面只展示了 two 模式其中 2 条，实际会返回 4 条（2 个版本 × {(Vocals)、(Instrumental)}）； twelve 模式会返回 24 条。真实条数以 clips 数组长度为准。

客户一般只需要保存 clips[].song_id，后续查询和下载都围绕这些 ID 进行。

批次与版本字段

需要自行归并历史结果时，使用分轨列表接口：

GET /api/music/songs?stem_only=1&source_song_id=<source_song_id>

优先按 stem_batch_id 分组；同一次提交的所有成功、处理中和失败结果共享该值。 如果历史数据的 stem_batch_id 为空，可再用 client_request_id 分组。

不要把 created_at 或 client_request_index 当作版本号。V1/V2 必须以 stem_version_index 为准；同一首歌连续发起两次分轨时，两次会有不同的 stem_batch_id。

注意事项

• 分轨结果不会出现在 GET /api/music/songs 歌曲历史里（该列表只返回普通生成歌曲）。提交成功后请立刻保存 clips[].song_id，否则后续无从查找。
• 轨道是独立作品：每条轨道都有自己的 song_id，需要各自轮询到完成、各自下载。
• 计费与条数无关：按次计费（two 1.2 元/次、twelve 3.0 元/次），返回 4 条还是 24 条都是同一价格。
• 下载：用该轨道的 song_id 走 POST /api/music/download-url / download-file（免费），或直接用查询结果里的 audio_url；取 MIDI 见MIDI 获取 API。
• 不要重复提交：分轨是同步接口，超时后请先用歌曲查询确认，不要直接重试（会重复下单、重复扣费）。
• 不再需要的轨道用分轨删除 API 隐藏。

查询分轨结果

提交成功后，使用 clips[].song_id 调用 POST /api/music/query 查询结果。

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

查询完成示例：

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

下载分轨文件

分轨结果完成后，可用下载接口下载单个分轨文件。

接口地址: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind 支持：

如需打包下载某条分轨结果的相关资源，可调用：

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

状态说明

常见错误

兼容说明

旧版文档中曾使用 success/task_id/vocals_url/instrumental_url 这类单对象示例。当前新版分轨以 clips[] 歌曲数组为准，每条分轨结果都拥有独立 song_id，后续查询和下载都围绕这些 song_id 进行。

相关接口

• 只想把人声和伴奏分开、不需要选择模式时，可用人声去除 API， 它是本接口的两轨快捷形式，按 stem_mode=two 同价计费。
• 不再需要的分轨轨道用分轨删除 API 隐藏（软删除，不扣费）。
• 取分轨的 MIDI 见MIDI 获取 API，取音频/封面等媒体见 歌曲媒体下载与试听 API。