# Suno Audio Separation Details

> Audio Generation

Query the asynchronous audio separation task status and result. When successful, `output.urls` contains downloadable URLs for the separated outputs,
`output.data` contains the Suno separation details as returned.

`output.data` is a Suno model-specific extension; its structure may vary by separation mode, and clients should preserve unknown fields.

**Returned data:**

The audio URL fields returned in the successful state (`task_status` is `Success`) vary by separation type:

- `separate_vocal`:
  - `originUrl`: The original mixed track.
  - `instrumentalUrl`: Instrumental track without vocals.
  - `vocalUrl`: Vocal-only track.
- `split_stem`:
  - `originUrl`: The original mixed track.
  - `vocalUrl`: Vocal-only track.
  - `backingVocalsUrl`: Backing vocal track.
  - `drumsUrl`: Drum track.
  - `bassUrl`: Bass track.
  - `guitarUrl`: Guitar track.
  - `keyboardUrl`: Keyboard track.
  - `percussionUrl`: Percussion track.
  - `stringsUrl`: String track.
  - `synthUrl`: Synth track.
  - `fxUrl`: Effects track.
  - `brassUrl`: Brass track.
  - `woodwindsUrl`: Woodwind track.
- `split_stem_advanced`:
  - Returns the URL field for the requested stem; the exact field depends on the actual response.

Audio file URLs are temporary; download and save the files promptly after the task succeeds.

**cURL example:**

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

## Endpoint

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | Task ID returned by the separation task submission endpoint. |

## Responses

- **200** — Separation task status response.
- **400** — Task ID or request parameters are invalid.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Suno Audio Separation API",
    "version": "1.0.0",
    "description": "Suno vocal and instrumental separation API.\nSubmit an asynchronous task and query its status to retrieve vocal, instrumental, or specified stem tracks.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse Suno API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Suno Audio Separation",
      "description": "Suno vocal and instrumental separation task operations."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "Suno Audio Separation"
        ],
        "operationId": "submitSunoVocalSeparationTask",
        "summary": "Suno Vocal and Instrumental Separation",
        "description": "Submit an asynchronous Suno audio separation task. The model is fixed to `suno-vocal-separation`; currently, only\nthe following two input methods are supported (choose one):\n\n1. Pass both `task_id` and `audio_id` in `parameters`;\n2. Pass a file URL in `input.audio_url`. When using `/v1/sunoapi/file-url-upload`,\n   use the `data.downloadUrl` from the response.\n\nThe two input methods cannot be combined, and neither `task_id` nor `audio_id` may be provided alone. When using\n`input.audio_url`, `parameters` may be omitted or may include `type`; for\n`split_stem_advanced`, `stem_name` is also required.\n\nWhen `type` is omitted, it defaults to `separate_vocal`. After submission succeeds, use the returned `task_id`\nto query the audio separation task status.\n\n**cURL example:**\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": "Separate vocals and accompaniment",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {},
                    "parameters": {
                      "task_id": "<suno-music-task-id>",
                      "audio_id": "<suno-audio-id>",
                      "type": "separate_vocal"
                    }
                  }
                },
                "splitStem": {
                  "summary": "Separate multiple stems",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {},
                    "parameters": {
                      "task_id": "<suno-music-task-id>",
                      "audio_id": "<suno-audio-id>",
                      "type": "split_stem"
                    }
                  }
                },
                "splitStemAdvanced": {
                  "summary": "Separate a specified stem",
                  "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": "Separate vocals and accompaniment using a file URL",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {
                      "audio_url": "https://example.com/source.mp3"
                    },
                    "parameters": {
                      "type": "separate_vocal"
                    }
                  }
                },
                "audioUrlSplitStemAdvanced": {
                  "summary": "Separate a specified stem using a file 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": "Use a file URL without parameters",
                  "value": {
                    "model": "suno-vocal-separation",
                    "input": {
                      "audio_url": "https://example.com/source.mp3"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Separation task submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoVocalSeparationSubmitResponse"
                },
                "example": {
                  "output": {
                    "task_id": "<separation-task-id>"
                  },
                  "request_id": "<request-id>"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Suno Audio Separation"
        ],
        "operationId": "getSunoVocalSeparationTaskStatus",
        "summary": "Suno Audio Separation Details",
        "description": "Query the asynchronous audio separation task status and result. When successful, `output.urls` contains downloadable URLs for the separated outputs,\n`output.data` contains the Suno separation details as returned.\n\n`output.data` is a Suno model-specific extension; its structure may vary by separation mode, and clients should preserve unknown fields.\n\n**Returned data:**\n\nThe audio URL fields returned in the successful state (`task_status` is `Success`) vary by separation type:\n\n- `separate_vocal`:\n  - `originUrl`: The original mixed track.\n  - `instrumentalUrl`: Instrumental track without vocals.\n  - `vocalUrl`: Vocal-only track.\n- `split_stem`:\n  - `originUrl`: The original mixed track.\n  - `vocalUrl`: Vocal-only track.\n  - `backingVocalsUrl`: Backing vocal track.\n  - `drumsUrl`: Drum track.\n  - `bassUrl`: Bass track.\n  - `guitarUrl`: Guitar track.\n  - `keyboardUrl`: Keyboard track.\n  - `percussionUrl`: Percussion track.\n  - `stringsUrl`: String track.\n  - `synthUrl`: Synth track.\n  - `fxUrl`: Effects track.\n  - `brassUrl`: Brass track.\n  - `woodwindsUrl`: Woodwind track.\n- `split_stem_advanced`:\n  - Returns the URL field for the requested stem; the exact field depends on the actual response.\n\nAudio file URLs are temporary; download and save the files promptly after the task succeeds.\n\n**cURL example:**\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": "Task ID returned by the separation task submission endpoint.",
            "schema": {
              "type": "string"
            },
            "example": "<separation-task-id>"
          }
        ],
        "responses": {
          "200": {
            "description": "Separation task status response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoVocalSeparationStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "Processing",
                    "value": {
                      "output": {
                        "task_id": "<separation-task-id>",
                        "task_status": "Pending",
                        "submit_time": 1786410000
                      },
                      "request_id": ""
                    }
                  },
                  "success": {
                    "summary": "Separation succeeded.",
                    "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": "Separation failed.",
                    "value": {
                      "output": {
                        "task_id": "<separation-task-id>",
                        "task_status": "Failure",
                        "submit_time": 1786410000,
                        "finish_time": 1786410010,
                        "error_message": "Error message returned by the upstream service"
                      },
                      "request_id": ""
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Task ID or request parameters are invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoSeparationErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "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": "Always `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": "Input audio. An empty object may be provided (in which case `task_id` and `audio_id` must be in `parameters`),\nor `audio_url` may be provided as the audio source.\n",
        "properties": {
          "audio_url": {
            "type": "string",
            "format": "uri",
            "minLength": 1,
            "description": "Audio file URL. The file upload endpoint response `data.downloadUrl` can be used directly."
          }
        }
      },
      "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": "Completed Suno music generation task ID."
          },
          "audio_id": {
            "type": "string",
            "minLength": 1,
            "description": "Suno audio ID of the stem to separate."
          },
          "type": {
            "type": "string",
            "default": "separate_vocal",
            "enum": [
              "separate_vocal",
              "split_stem",
              "split_stem_advanced"
            ],
            "description": "Separation mode. Defaults to `separate_vocal` when omitted."
          },
          "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": "Name of the stem to separate. Required for `split_stem_advanced`; must be one of the following values.\n"
          }
        }
      },
      "SunoVocalSeparationSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Newly created separation task ID."
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "SunoVocalSeparationStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/SunoVocalSeparationStatusOutput"
          },
          "usage": {
            "type": "object",
            "additionalProperties": false,
            "description": "Usage object. Failed tasks are not billed."
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "SunoVocalSeparationStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Separation task ID."
          },
          "task_status": {
            "type": "string",
            "enum": [
              "Pending",
              "Running",
              "Success",
              "Failure"
            ],
            "description": "Separation task status."
          },
          "urls": {
            "type": "array",
            "description": "List of separated output URLs.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "Task submission timestamp."
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "Task completion timestamp."
          },
          "error_message": {
            "type": "string",
            "description": "Error message returned when the task fails."
          },
          "data": {
            "$ref": "#/components/schemas/SunoSeparationData"
          }
        }
      },
      "SunoSeparationData": {
        "type": "object",
        "description": "Suno audio separation details; model-specific fields.",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "originUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the original mixed track."
          },
          "originData": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SunoStem"
            }
          },
          "instrumentalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the instrumental track without vocals."
          },
          "vocalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the vocal-only track."
          },
          "backingVocalsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the backing vocal track."
          },
          "drumsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the drum track."
          },
          "bassUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the bass track."
          },
          "guitarUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the guitar track."
          },
          "keyboardUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the keyboard track."
          },
          "percussionUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the percussion track."
          },
          "stringsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the string track."
          },
          "synthUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the synth track."
          },
          "fxUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the effects track."
          },
          "brassUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the brass track."
          },
          "woodwindsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Download URL for the woodwind track."
          }
        }
      },
      "SunoStem": {
        "type": "object",
        "properties": {
          "duration": {
            "type": "number",
            "description": "Stem duration, in seconds."
          },
          "audio_url": {
            "type": "string",
            "format": "uri",
            "description": "Stem download URL."
          },
          "stem_type_group_name": {
            "type": "string",
            "description": "Stem type name."
          },
          "id": {
            "type": "string",
            "description": "Separated stem ID."
          }
        }
      },
      "SunoSeparationErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "description": "Error object; actual fields may vary."
      }
    }
  }
}
```