# 分轨提取
> 从已有歌曲中分离出指定的一条分轨，异步任务
> 支持 90 多种乐器与声部类型
> 只要人声与伴奏用全量分轨，要特定乐器用这个
`POST /v1/music/generations/stems`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，默认 `suno`，当前仅 `suno`。
- `task_id` (string / 必填) — 产出源音轨那次任务的 task_id。缺失或无法定位源音轨时，提交阶段即返回 400。
- `audio_index` (integer / 可选) — 指定 `data.result.music[]` 中的第几首，默认 `1`。一次生成通常有 2 首，索引为 1 或 2。
- `stem_type` (string / 可选) — 要提取的分轨类型，默认 `lead_vocal`。 取值见下方分类。注意 `808` 必须作为字符串传递。
- `audio_format` (string / 可选) — 输出音频格式，取值 `mp3`、`m4a`、`wav`。
## stem_type 可选值
**人声类**
`lead_vocal`、`backing_vocals`、`choir`、`synth_voice`
**鼓与打击乐**
`drum_kit`、`electronic_drum_kit`、`kick`、`snare`、`hi_hat`、`cymbals`、`hand_clap`、`percussion`、`tambourine`、`shaker`、`cowbell`、`bells`、`congas`、`bongos`、`djembe`、`tabla`、`taiko`、`timpani`、`steel_drums`、`music_box`、`glockenspiel`
**贝斯类**
`bass`、`synth_bass`、`electric_bass`、`upright_bass`、`double_bass`、`808`
**吉他类**
`guitar`、`acoustic_guitar`、`electric_guitar`、`lead_guitar`、`lead_electric_guitar`、`rhythm_electric_guitar`、`distorted_electric_guitar`、`bass_guitar`、`pedal_steel_guitar`、`lap_steel_guitar`、`fiddle`、`banjo`、`mandolin`、`ukulele`、`sitar`、`koto`
**键盘类**
`piano`、`electric_piano`、`digital_piano`、`rhodes`、`organ`、`synth`、`synth_pad`、`synth_keys`、`synth_lead`、`arpeggiator`、`keyboards`、`harpsichord`、`celesta`、`accordion`、`melodica`
**管乐类**
`brass_section`、`synth_brass`、`trumpet`、`trombone`、`tuba`、`french_horn`、`horns`、`saxophone`、`alto_saxophone`、`tenor_saxophone`、`baritone_saxophone`、`clarinet`、`oboe`、`bassoon`、`flute`、`piccolo`、`woodwinds`、`harmonica`、`bagpipes`、`whistle`、`didgeridoo`
**弦乐类**
`string_section`、`synth_strings`、`violin`、`viola`、`cello`、`harp`、`orchestra`
**其他**
`sound_effects`、`risers`、`drone`、`theremin`、`vibraphone`、`marimba`、`xylophone`
## 响应
- `code` (integer) — 响应状态码，成功时为 200。
- `data[].status` (string) — 提交成功后为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询查询结果。
轮询用 `GET /v1/music/tasks/{task_id}`，建议每 3 到 5 秒一次，直到 `status` 为 `completed` 或 `failed`。
完成后分轨音频的 URL 出现在 `data.result` 里。失败原因写在 `data.error.message`，预扣额度会自动退回。
> **Note:** 
> 引用源音轨只需 `task_id` 加 `audio_index`，无需记录其他标识。`stem_type` 省略时默认 `lead_vocal`，传非法值会触发 400。
> **Note:** 
> `808` 是唯一一个纯数字的取值，必须传字符串 `"808"`。传数字 `808` 可能被解析成别的含义。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**分轨提取{Extract stems}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/stems' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "stem_type": "drum_kit",
    "audio_format": "wav"
  }'
```
**分轨提取{Extract stems}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/stems",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
        "audio_index": 1,
        "stem_type": "drum_kit",
        "audio_format": "wav",
    },
)
print(res.json()["data"][0]["task_id"])
```
**分轨提取{Extract stems}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/stems";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "stem_type": "drum_kit",
    "audio_format": "wav"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 分轨提取{Extract stems}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C99M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**取贝斯轨{Bass stem}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/stems' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "suno",
  "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "audio_index": 2,
  "stem_type": "bass",
  "audio_format": "wav"
}'
```
**取贝斯轨{Bass stem}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/stems"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "suno",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
      "audio_index": 2,
      "stem_type": "bass",
      "audio_format": "wav"
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**取贝斯轨{Bass stem}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/stems", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 2,
    "stem_type": "bass",
    "audio_format": "wav"
  }),
});
console.log(await res.json());
```
**200 取贝斯轨{Bass stem}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C99M0HP1GJWBJYZMKX1XS1" }
  ]
}
```