# Suno 音频分离详情

> 音频生成

查询音频分离异步任务状态和结果。任务成功时，`output.urls` 返回可下载的分离产物 URL，
`output.data` 原样承载 Suno 的分离详情。

`output.data` 是 Suno 模型专属扩展字段，不同分离模式的结构可能不同；客户端应保留未知字段。

**返回数据说明：**

根据提交任务时选择的分离类型，成功状态（`task_status` 为 `Success`）下返回的音频 URL 字段会有所不同：

- `separate_vocal`：
  - `originUrl`：原始混合音轨。
  - `instrumentalUrl`：无人声的伴奏音轨。
  - `vocalUrl`：仅包含人声的音轨。
- `split_stem`：
  - `originUrl`：原始混合音轨。
  - `vocalUrl`：仅包含人声的音轨。
  - `backingVocalsUrl`：仅包含和声的音轨。
  - `drumsUrl`：仅包含鼓声的音轨。
  - `bassUrl`：仅包含贝斯的音轨。
  - `guitarUrl`：仅包含吉他的音轨。
  - `keyboardUrl`：仅包含键盘的音轨。
  - `percussionUrl`：仅包含打击乐的音轨。
  - `stringsUrl`：仅包含弦乐的音轨。
  - `synthUrl`：仅包含合成器的音轨。
  - `fxUrl`：仅包含音效的音轨。
  - `brassUrl`：仅包含铜管乐的音轨。
  - `woodwindsUrl`：仅包含木管乐的音轨。
- `split_stem_advanced`：
  - 返回所请求音轨对应的 URL 字段，具体字段以实际响应为准。

音频文件 URL 具有时效性，建议在任务成功后及时下载并保存音频文件，避免链接过期后无法访问。

**cURL 示例：**

```bash
curl --request GET \
  'https://api.modelverse.cn/v1/tasks/status?task_id=<separation-task-id>' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## 请求地址

`GET https://api.modelverse.cn/v1/tasks/status`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | 分离任务提交接口返回的任务 ID。 |

## 响应

- **200** — 分离任务状态响应。
- **400** — 任务 ID 或请求参数无效。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Suno 音频分离接口文档",
    "version": "1.0.0",
    "description": "这是 Suno 人声和乐器分离接口文档。\n通过提交异步任务并查询任务状态，可以获取人声、伴奏或指定乐器音轨。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse Suno API 端点。"
    }
  ],
  "tags": [
    {
      "name": "Suno 音频分离",
      "description": "Suno 人声和乐器分离任务操作。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "Suno 音频分离"
        ],
        "operationId": "submitSunoVocalSeparationTask",
        "summary": "Suno 人声和乐器分离",
        "description": "提交 Suno 音频分离异步任务。模型固定为 `suno-vocal-separation`，当前仅支持\n以下两种输入方式，二选一：\n\n1. 在 `parameters` 中同时传入 `task_id` 和 `audio_id`；\n2. 在 `input` 中传入 `audio_url` 文件 URL。通过 `/v1/sunoapi/file-url-upload`\n   上传文件时，应使用响应中的 `data.downloadUrl`。\n\n两种输入方式不能混用，也不能只传 `task_id` 或只传 `audio_id`。使用\n`input.audio_url` 时，`parameters` 可以省略，也可以传入 `type`；在\n`split_stem_advanced` 模式下还需要传入 `stem_name`。\n\n`type` 省略时默认为 `separate_vocal`。任务提交成功后，使用返回的 `task_id`\n调用音频分离详情接口查询结果。\n\n**cURL 示例：**\n\n```bash\ncurl --request POST 'https://api.modelverse.cn/v1/tasks/submit' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"model\": \"suno-vocal-separation\",\n    \"input\": {},\n    \"parameters\": {\n      \"task_id\": \"<suno-music-task-id>\",\n      \"audio_id\": \"<suno-audio-id>\",\n      \"type\": \"separate_vocal\"\n    }\n  }'\n```\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SunoVocalSeparationSubmitRequest"
              },
              "examples": {
                "separateVocal": {
                  "summary": "分离人声和伴奏",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {},
                    "parameters": {
                      "task_id": "<suno-music-task-id>",
                      "audio_id": "<suno-audio-id>",
                      "type": "separate_vocal"
                    }
                  }
                },
                "splitStem": {
                  "summary": "多音轨分离",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {},
                    "parameters": {
                      "task_id": "<suno-music-task-id>",
                      "audio_id": "<suno-audio-id>",
                      "type": "split_stem"
                    }
                  }
                },
                "splitStemAdvanced": {
                  "summary": "指定音轨分离",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {},
                    "parameters": {
                      "task_id": "<suno-music-task-id>",
                      "audio_id": "<suno-audio-id>",
                      "type": "split_stem_advanced",
                      "stem_name": "Drum Kit"
                    }
                  }
                },
                "audioUrl": {
                  "summary": "使用文件 URL 分离人声和伴奏",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {
                      "audio_url": "https://example.com/source.mp3"
                    },
                    "parameters": {
                      "type": "separate_vocal"
                    }
                  }
                },
                "audioUrlSplitStemAdvanced": {
                  "summary": "使用文件 URL 指定音轨分离",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {
                      "audio_url": "https://example.com/source.mp3"
                    },
                    "parameters": {
                      "type": "split_stem_advanced",
                      "stem_name": "Drum Kit"
                    }
                  }
                },
                "audioUrlWithoutParameters": {
                  "summary": "使用文件 URL 且省略 parameters",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {
                      "audio_url": "https://example.com/source.mp3"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分离任务提交成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoVocalSeparationSubmitResponse"
                },
                "example": {
                  "output": {
                    "task_id": "<separation-task-id>"
                  },
                  "request_id": "<request-id>"
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Suno 音频分离"
        ],
        "operationId": "getSunoVocalSeparationTaskStatus",
        "summary": "Suno 音频分离详情",
        "description": "查询音频分离异步任务状态和结果。任务成功时，`output.urls` 返回可下载的分离产物 URL，\n`output.data` 原样承载 Suno 的分离详情。\n\n`output.data` 是 Suno 模型专属扩展字段，不同分离模式的结构可能不同；客户端应保留未知字段。\n\n**返回数据说明：**\n\n根据提交任务时选择的分离类型，成功状态（`task_status` 为 `Success`）下返回的音频 URL 字段会有所不同：\n\n- `separate_vocal`：\n  - `originUrl`：原始混合音轨。\n  - `instrumentalUrl`：无人声的伴奏音轨。\n  - `vocalUrl`：仅包含人声的音轨。\n- `split_stem`：\n  - `originUrl`：原始混合音轨。\n  - `vocalUrl`：仅包含人声的音轨。\n  - `backingVocalsUrl`：仅包含和声的音轨。\n  - `drumsUrl`：仅包含鼓声的音轨。\n  - `bassUrl`：仅包含贝斯的音轨。\n  - `guitarUrl`：仅包含吉他的音轨。\n  - `keyboardUrl`：仅包含键盘的音轨。\n  - `percussionUrl`：仅包含打击乐的音轨。\n  - `stringsUrl`：仅包含弦乐的音轨。\n  - `synthUrl`：仅包含合成器的音轨。\n  - `fxUrl`：仅包含音效的音轨。\n  - `brassUrl`：仅包含铜管乐的音轨。\n  - `woodwindsUrl`：仅包含木管乐的音轨。\n- `split_stem_advanced`：\n  - 返回所请求音轨对应的 URL 字段，具体字段以实际响应为准。\n\n音频文件 URL 具有时效性，建议在任务成功后及时下载并保存音频文件，避免链接过期后无法访问。\n\n**cURL 示例：**\n\n```bash\ncurl --request GET \\\n  'https://api.modelverse.cn/v1/tasks/status?task_id=<separation-task-id>' \\\n  --header 'Authorization: Bearer YOUR_API_KEY'\n```\n",
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "分离任务提交接口返回的任务 ID。",
            "schema": {
              "type": "string"
            },
            "example": "<separation-task-id>"
          }
        ],
        "responses": {
          "200": {
            "description": "分离任务状态响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoVocalSeparationStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "处理中",
                    "value": {
                      "output": {
                        "task_id": "<separation-task-id>",
                        "task_status": "Pending",
                        "submit_time": 1786410000
                      },
                      "request_id": ""
                    }
                  },
                  "success": {
                    "summary": "分离成功",
                    "value": {
                      "output": {
                        "task_id": "<separation-task-id>",
                        "task_status": "Success",
                        "submit_time": 1786410000,
                        "finish_time": 1786410100,
                        "urls": [
                          "https://example.com/instrumental.mp3",
                          "https://example.com/vocals.mp3"
                        ],
                        "data": {
                          "id": null,
                          "originUrl": null,
                          "originData": [
                            {
                              "duration": 245.6,
                              "audio_url": "https://example.com/vocals.mp3",
                              "stem_type_group_name": "Vocals",
                              "id": "vocal-audio-id"
                            },
                            {
                              "duration": 245.6,
                              "audio_url": "https://example.com/instrumental.mp3",
                              "stem_type_group_name": "Instrumental",
                              "id": "instrumental-audio-id"
                            }
                          ],
                          "instrumentalUrl": "https://example.com/instrumental.mp3",
                          "vocalUrl": "https://example.com/vocals.mp3",
                          "backingVocalsUrl": null,
                          "drumsUrl": null,
                          "bassUrl": null,
                          "guitarUrl": null,
                          "keyboardUrl": null,
                          "percussionUrl": null,
                          "stringsUrl": null,
                          "synthUrl": null,
                          "fxUrl": null,
                          "brassUrl": null,
                          "woodwindsUrl": null
                        }
                      },
                      "usage": {},
                      "request_id": ""
                    }
                  },
                  "failure": {
                    "summary": "分离失败",
                    "value": {
                      "output": {
                        "task_id": "<separation-task-id>",
                        "task_status": "Failure",
                        "submit_time": 1786410000,
                        "finish_time": 1786410010,
                        "error_message": "上游返回的错误信息"
                      },
                      "request_id": ""
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "任务 ID 或请求参数无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API Key。"
      }
    },
    "schemas": {
      "SunoVocalSeparationSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "suno-vocal-separation",
            "description": "固定使用 `suno-vocal-separation`。"
          },
          "input": {
            "$ref": "#/components/schemas/SunoVocalSeparationInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/SunoVocalSeparationParameters"
          }
        },
        "allOf": [
          {
            "if": {
              "required": [
                "input"
              ],
              "properties": {
                "input": {
                  "required": [
                    "audio_url"
                  ]
                }
              }
            },
            "then": {
              "properties": {
                "parameters": {
                  "not": {
                    "anyOf": [
                      {
                        "required": [
                          "task_id"
                        ]
                      },
                      {
                        "required": [
                          "audio_id"
                        ]
                      }
                    ]
                  }
                }
              }
            },
            "else": {
              "required": [
                "parameters"
              ],
              "properties": {
                "parameters": {
                  "required": [
                    "task_id",
                    "audio_id"
                  ]
                }
              }
            }
          }
        ]
      },
      "SunoVocalSeparationInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "输入音频。可传空对象（此时必须在 `parameters` 中传入 `task_id` 和 `audio_id`），\n或传入 `audio_url` 使用文件 URL 作为音频来源。\n",
        "properties": {
          "audio_url": {
            "type": "string",
            "format": "uri",
            "minLength": 1,
            "description": "音频文件 URL。文件上传接口返回的 `data.downloadUrl` 可直接使用。"
          }
        }
      },
      "SunoVocalSeparationParameters": {
        "type": "object",
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {
                "type": {
                  "const": "split_stem_advanced"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "required": [
                "stem_name"
              ]
            }
          }
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "minLength": 1,
            "description": "已完成的 Suno 音乐生成任务 ID。"
          },
          "audio_id": {
            "type": "string",
            "minLength": 1,
            "description": "待分离音轨的 Suno 音频 ID。"
          },
          "type": {
            "type": "string",
            "default": "separate_vocal",
            "enum": [
              "separate_vocal",
              "split_stem",
              "split_stem_advanced"
            ],
            "description": "分离模式。省略时默认为 `separate_vocal`。"
          },
          "stem_name": {
            "type": "string",
            "enum": [
              "Lead Vocal",
              "Drum Kit",
              "Kick",
              "Snare",
              "Risers",
              "Bass",
              "Backing Vocals",
              "Piano",
              "Electric Guitar",
              "Percussion",
              "String Section",
              "Synth",
              "Acoustic Guitar",
              "Sound Effects",
              "Synth Pad",
              "Synth Bass",
              "Guitar",
              "Brass Section",
              "Organ",
              "Electronic Drum Kit",
              "Lead Electric Guitar",
              "Synth Keys",
              "Rhythm Electric Guitar",
              "Electric Piano",
              "Upright Bass",
              "Keyboards",
              "Distorted Electric Guitar",
              "Synth Strings",
              "Synth Lead",
              "Woodwinds",
              "Rhythm Acoustic Guitar",
              "Flute",
              "Harp",
              "Tambourine",
              "Trumpet",
              "Arpeggiator",
              "Accordion",
              "Fiddle",
              "Pedal Steel Guitar",
              "Synth Voice",
              "Violin",
              "Digital Piano",
              "Synth Brass",
              "Mandolin",
              "Choir",
              "Banjo",
              "Bells",
              "Clarinet",
              "Tenor Saxophone",
              "Trombone",
              "Shaker",
              "French Horn",
              "Glockenspiel",
              "Electric Bass",
              "Cello",
              "Timpani",
              "Harmonica",
              "Marimba",
              "Vibraphone",
              "Lap Steel Guitar",
              "Saxophone",
              "Orchestra",
              "Horns",
              "Cymbals",
              "Hand Clap",
              "Oboe",
              "Celesta",
              "Congas",
              "Drone",
              "Alto Saxophone",
              "Double Bass",
              "Ukulele",
              "Harpsichord",
              "Baritone Saxophone",
              "Xylophone",
              "Tuba",
              "Bass Guitar",
              "Whistle",
              "Lead Guitar",
              "Rhodes",
              808,
              "Bongos",
              "Bassoon",
              "Cowbell",
              "Viola",
              "Sitar",
              "Steel Drums",
              "Piccolo",
              "Theremin",
              "Bagpipes",
              "Hi-Hat",
              "Music Box",
              "Melodica",
              "Tabla",
              "Koto",
              "Djembe",
              "Taiko",
              "Didgeridoo"
            ],
            "description": "指定分离音轨名称。`split_stem_advanced` 模式必填，必须使用以下可选值之一。\n"
          }
        }
      },
      "SunoVocalSeparationSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "新创建的分离任务 ID。"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "唯一请求标识。"
          }
        }
      },
      "SunoVocalSeparationStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/SunoVocalSeparationStatusOutput"
          },
          "usage": {
            "type": "object",
            "additionalProperties": false,
            "description": "用量对象。失败任务不计费。"
          },
          "request_id": {
            "type": "string",
            "description": "唯一请求标识。"
          }
        }
      },
      "SunoVocalSeparationStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "分离任务 ID。"
          },
          "task_status": {
            "type": "string",
            "enum": [
              "Pending",
              "Running",
              "Success",
              "Failure"
            ],
            "description": "分离任务状态。"
          },
          "urls": {
            "type": "array",
            "description": "分离产物 URL 列表。",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "任务提交时间戳。"
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "任务完成时间戳。"
          },
          "error_message": {
            "type": "string",
            "description": "任务失败时返回的错误信息。"
          },
          "data": {
            "$ref": "#/components/schemas/SunoSeparationData"
          }
        }
      },
      "SunoSeparationData": {
        "type": "object",
        "description": "Suno 返回的音频分离详情，模型专属字段。",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "originUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "原始混合音轨下载 URL。"
          },
          "originData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SunoStem"
            }
          },
          "instrumentalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "无人声的伴奏音轨下载 URL。"
          },
          "vocalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含人声的音轨下载 URL。"
          },
          "backingVocalsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含和声的音轨下载 URL。"
          },
          "drumsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含鼓声的音轨下载 URL。"
          },
          "bassUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含贝斯的音轨下载 URL。"
          },
          "guitarUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含吉他的音轨下载 URL。"
          },
          "keyboardUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含键盘的音轨下载 URL。"
          },
          "percussionUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含打击乐的音轨下载 URL。"
          },
          "stringsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含弦乐的音轨下载 URL。"
          },
          "synthUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含合成器的音轨下载 URL。"
          },
          "fxUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含音效的音轨下载 URL。"
          },
          "brassUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含铜管乐的音轨下载 URL。"
          },
          "woodwindsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "仅包含木管乐的音轨下载 URL。"
          }
        }
      },
      "SunoStem": {
        "type": "object",
        "properties": {
          "duration": {
            "type": "number",
            "description": "音轨时长，单位为秒。"
          },
          "audio_url": {
            "type": "string",
            "format": "uri",
            "description": "音轨下载 URL。"
          },
          "stem_type_group_name": {
            "type": "string",
            "description": "音轨类型名称。"
          },
          "id": {
            "type": "string",
            "description": "分离音轨 ID。"
          }
        }
      },
      "SunoSeparationErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "description": "错误对象，具体字段以实际响应为准。"
      }
    }
  }
}
```