> ## Documentation Index > Fetch the complete documentation index at: https://docs.apistable.com/llms.txt > Use this file to discover all available pages before exploring further. # 人声分离与分轨 > 工具箱模式填写音频 URL；原生分轨选择本站歌曲 ID，按返回轨道分别试听和下载。 > 能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。 ## 调用步骤 工具箱模式填写音频 URL；原生分轨选择本站歌曲 ID，按返回轨道分别试听和下载。 * 1. 按下方示例准备输入，将占位地址和 ID 换成你有权使用的资源。 * 2. 将 model 设为 suno\_separate\_vocals，参数放在 input 内。提交一次并保存返回的 task\_id。 * 3. 查询已保存的任务，或接收回调。任务仍在处理中时继续等待，不重新提交同一操作。 * 遍历 result.stems，读取各轨的 download\_url 和到期时间，以实际返回的轨名和数量为准。 ## 创建任务 将model和input发送到统一任务入口；可在顶层传公开HTTPS callback\_url。资源ID均为本账户的本站ID。当前音乐积分扣除未启用。 ```json theme={null} { "model": "suno_separate_vocals", "input": { "type": "separate_vocal", "upload_url": "https://example.com/song.mp3" } } ``` ## 受理响应 HTTP 200仅表示受理。查询GET /api/v1/tasks/\{task\_id}，直到data.status为succeeded或failed。成功后读取data.result；失败原因位于data.message。 ```json theme={null} { "code": 200, "msg": "success", "data": { "task_id": "YOUR_TASK_ID" } } ``` ## 参数：type = separate\_vocal | 字段 | 类型 | 必填 | 说明与限制 | | - | - | - | - | | type | string | 是 | separate\_vocal（2 轨）、split\_stem（4/6 轨），或原生 split\_stem\_advanced。 = separate\_vocal | | upload\_url | string | 是 | 公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。 | | output\_format | string | 否 / 依条件 | 工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。 values: mp3, wav, flac, ogg, m4a, aac; default: wav | ## 参数：type = split\_stem | 字段 | 类型 | 必填 | 说明与限制 | | - | - | - | - | | type | string | 是 | separate\_vocal（2 轨）、split\_stem（4/6 轨），或原生 split\_stem\_advanced。 = split\_stem | | upload\_url | string | 是 | 公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。 | | stem\_mode | number | 是 | 工具箱分轨：4 或 6 轨；人声分离在后台固定为 2 轨。 values: 4, 6 | | output\_format | string | 否 / 依条件 | 工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。 values: mp3, wav, flac, ogg, m4a, aac; default: wav | ## 参数：type = split\_stem\_advanced | 字段 | 类型 | 必填 | 说明与限制 | | - | - | - | - | | type | string | 是 | separate\_vocal（2 轨）、split\_stem（4/6 轨），或原生 split\_stem\_advanced。 = split\_stem\_advanced | | audio\_id | string | 是 | 本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task\_id或外部URL。 maxLength: 200 | | stem\_name | string | 否 / 依条件 | 原生抽取的轨道名。当前仅 Piano 有明确文档并开放；省略时使用十二轨分离。 maxLength: 100 | ## 输入与限制 下方Schema列出支持字段、类型和基础限制；还须遵守“重要条件”，跨字段与来源资源校验不完全体现在JSON Schema中。未知参数会被拒绝。URL 参数仅接受公开 HTTPS 地址，不接受文件对象。 ```json theme={null} { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "separate_vocal", "description": "separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。" }, "upload_url": { "type": "string", "format": "uri", "description": "公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。" }, "output_format": { "default": "wav", "type": "string", "enum": [ "mp3", "wav", "flac", "ogg", "m4a", "aac" ], "description": "工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。" } }, "required": [ "type", "upload_url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "split_stem", "description": "separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。" }, "upload_url": { "type": "string", "format": "uri", "description": "公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。" }, "stem_mode": { "anyOf": [ { "type": "number", "const": 4 }, { "type": "number", "const": 6 } ], "description": "工具箱分轨：4 或 6 轨；人声分离在后台固定为 2 轨。" }, "output_format": { "default": "wav", "type": "string", "enum": [ "mp3", "wav", "flac", "ogg", "m4a", "aac" ], "description": "工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。" } }, "required": [ "type", "upload_url", "stem_mode" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "split_stem_advanced", "description": "separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。" }, "audio_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task_id或外部URL。" }, "stem_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "原生抽取的轨道名。当前仅 Piano 有明确文档并开放；省略时使用十二轨分离。" } }, "required": [ "type", "audio_id" ], "additionalProperties": false } ] } ``` ## 重要条件 * separate\_vocal与split\_stem使用upload\_url，音频上限100 MiB。separate\_vocal请求两轨；split\_stem必须传stem\_mode=4或6。output\_format使用所列格式，默认wav。 * 原生split\_stem\_advanced传audio\_id，不传upload\_url或output\_format；省略stem\_name为十二轨分离，单轨抽取当前仅开放Piano，其他名称返回42201。结果可能包含多组轨道，请遍历实际stems数组，不假定固定条数。 * 音频URL必须包含可读且时长大于零的MP3/WAV/FLAC/OGG/M4A/AAC音轨，每个文件最多100 MiB。URL须为可公开读取的HTTPS地址、端口443，不含用户名密码或私网地址，且应持续可访问直到任务结束。 * 上传文件保留24小时，生成文件保留14天，任务详情保留30天；复用文件沿用原到期时间。有效Voice/Persona身份映射与任务日志清理分开处理，请及时下载需长期保存的文件。 ## 结果 Schema 创建响应为 \{code:200,msg:"success",data:\{task\_id}}，轮询 GET /api/v1/tasks/\{task\_id}。成功时 data.result 为符合下方 Schema 的对象，其他状态为 null；input 仍为 JSON 字符串。 ```json theme={null} { "type": "object", "required": [ "stems" ], "properties": { "stems": { "type": "array", "items": { "type": "object", "properties": { "stem_name": { "type": [ "string", "null" ] }, "download_url": { "type": "string" }, "expires_at": { "type": "string" } } } } }, "additionalProperties": false } ``` ## 相关流程 [Voice 完整四步](https://docs.apistable.com/zh/suno-voice-workflow.md) [文件上传](https://docs.apistable.com/zh/file-upload.md) [回调](https://docs.apistable.com/zh/webhooks.md) ## OpenAPI ````yaml openapi-suno-separate-vocals-zh.json POST /api/v1/tasks/create_task openapi: 3.1.0 info: title: APIstable API version: 1.0.0-preview description: >- Public /api/v1 protocol. Valid API keys have the same account-scoped access. No client submission idempotency or max_credits. Enabled Suno operations use PayAPI and durable task processing. Media uses R2: uploads 24 hours, generated files 14 days, task logs 30 days. Music credit deduction is disabled. Unconfigured operations and LLM return 503. servers: - url: https://apistable.com description: APIstable API security: [] paths: /api/v1/tasks/create_task: post: summary: 人声分离与分轨 description: 工具箱模式填写音频 URL；原生分轨选择本站歌曲 ID，按返回轨道分别试听和下载。 operationId: suno_separate_vocals requestBody: required: true content: application/json: schema: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - suno_separate_vocals example: suno_separate_vocals input: $schema: https://json-schema.org/draft/2020-12/schema oneOf: - type: object properties: type: type: string const: separate_vocal description: >- separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。 upload_url: type: string format: uri description: >- 公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。 output_format: default: wav type: string enum: - mp3 - wav - flac - ogg - m4a - aac description: 工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。 required: - type - upload_url additionalProperties: false - type: object properties: type: type: string const: split_stem description: >- separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。 upload_url: type: string format: uri description: >- 公开HTTPS音频URL，端口443且不含用户名密码。接受包含可读音轨的MP3/WAV/FLAC/OGG/M4A/AAC，大小限制见具体操作。 stem_mode: anyOf: - type: number const: 4 - type: number const: 6 description: 工具箱分轨：4 或 6 轨；人声分离在后台固定为 2 轨。 output_format: default: wav type: string enum: - mp3 - wav - flac - ogg - m4a - aac description: 工具箱输出：mp3、wav（默认）、flac、ogg、m4a 或 aac；原生轨道抽取不接受此参数。 required: - type - upload_url - stem_mode additionalProperties: false - type: object properties: type: type: string const: split_stem_advanced description: >- separate_vocal（2 轨）、split_stem（4/6 轨），或原生 split_stem_advanced。 audio_id: type: string minLength: 1 maxLength: 200 description: 本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task_id或外部URL。 stem_name: type: string minLength: 1 maxLength: 100 description: 原生抽取的轨道名。当前仅 Piano 有明确文档并开放；省略时使用十二轨分离。 required: - type - audio_id additionalProperties: false callback_url: type: string format: uri description: >- Optional public HTTPS endpoint for signed completion callbacks; no redirects or private IPs. example: model: suno_separate_vocals input: type: separate_vocal upload_url: https://example.com/song.mp3 responses: '200': description: Accepted task. Poll the common task endpoint or use callback_url. content: application/json: schema: type: object required: - code - msg - data additionalProperties: false properties: code: const: 200 msg: const: success data: type: object required: - task_id additionalProperties: false properties: task_id: type: string '400': description: >- 40001 invalid JSON, 40002 invalid input/callback, 40003 unsupported parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: '40201: Insufficient credits (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '40401: Unknown model or resource not found in this account.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '40901: Resource belongs to a different provider account.' content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: '41001: Source audio or temporary resource has expired.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '41301: Request too large.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '42201: Requested music combination is not enabled.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '42901: Rate/concurrency limit (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: '50301: Service/provider unavailable. No live submission or charge.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Error: type: object required: - code - msg - data properties: code: type: integer msg: type: string data: type: 'null' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Every valid key can submit and query its own account. Revoked keys are rejected. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.