> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload and Separate Vocals
> Upload audio and separate it into multiple stems
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
**Vocal Separation Options:**
* [separate-vocals](/api-manual/music-series/vocal-remover/separate-vocals): Does not support uploading audio, 2-stem split, based on Suno
* [stem-split](/api-manual/music-series/vocal-remover/stem-split): Does not support uploading audio, 12-stem split, based on Suno
* [upload-and-separate-vocals](/api-manual/music-series/vocal-remover/upload-and-separate-vocals): Supports uploading audio, 7-stem split
* This endpoint uploads audio and separates it into multiple stems
* Creates separate tracks for bass, drums, piano, guitar, vocals, and other
* Useful for remixing or isolating specific instruments from uploaded audio
## Parameter Details
* `audio_url` (required): URL of the audio file to upload and separate
* `title` (optional): Title for the separation task
* `model_name` (optional): Separation model to use. Default: `base`
* `base`: Standard separation quality
* `enhanced`: Higher quality separation with better accuracy
* `instrumental`: Optimized for instrumental tracks
* `output_type` (optional): Type of output stems to generate. Default: `general`
* `general`: All available stems
* `bass`: Bass track only
* `drums`: Drums track only
* `other`: Other instruments
* `piano`: Piano track only
* `guitar`: Guitar track only
* `vocals`: Vocals track only
## OpenAPI
````yaml /api-manual/music-series/vocal-remover/upload-and-separate-vocals.json POST /api/generate/submit
openapi: 3.0.0
info:
title: Vidgo API - Upload and Separate Vocals API
description: Upload audio and separate it into multiple stems
version: 1.0.0
servers:
- url: https://api.vidgo.ai
description: Production server
security:
- BearerAuth: []
paths:
/api/generate/submit:
post:
tags:
- Audio Processing
summary: Submit Upload and Separate Vocals Task
description: Upload an audio file and separate it into multiple stems
operationId: submitUploadAndSeparateVocalsTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitRequest'
examples:
basic-general:
summary: Basic Mode - General Output
value:
model: upload-and-separate-vocals
callback_url: https://your-domain.com/callback
input:
title: My Audio Track
audio_url: https://example.com/audio/my-track.mp3
model_name: base
output_type: general
enhanced-vocals:
summary: Enhanced Mode - Vocals Only
value:
model: upload-and-separate-vocals
callback_url: https://your-domain.com/callback
input:
title: My Audio Track
audio_url: https://example.com/audio/my-track.mp3
model_name: enhanced
output_type: vocals
instrumental-drums:
summary: Instrumental Mode - Drums Only
value:
model: upload-and-separate-vocals
callback_url: https://your-domain.com/callback
input:
title: My Audio Track
audio_url: https://example.com/audio/my-track.mp3
model_name: instrumental
output_type: drums
responses:
'200':
description: Task submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitResponse'
'409':
description: Separation already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 409
error:
message: Separation already exists for this audio
type: conflict_error
components:
schemas:
SubmitRequest:
type: object
required:
- model
- callback_url
- input
properties:
model:
type: string
description: |-
API model identifier.
Must be `upload-and-separate-vocals` for this endpoint.
enum:
- upload-and-separate-vocals
example: upload-and-separate-vocals
callback_url:
type: string
format: uri
description: >-
Webhook callback URL for result notifications.
The endpoint will receive POST requests with separation completion
status and download URLs for each track.
example: https://your-domain.com/callback
input:
type: object
required:
- audio_url
description: Input parameters for upload and vocal separation
properties:
title:
type: string
description: |-
Title for the separation task (optional).
Used to identify and organize your separated audio files.
example: My Audio Track
audio_url:
type: string
format: uri
description: |-
URL of the audio file to upload and separate.
Must be a publicly accessible URL to the audio file.
example: https://example.com/audio/my-track.mp3
model_name:
type: string
description: |-
Separation model to use.
- `base`: Standard separation quality (default)
- `enhanced`: Higher quality separation with better accuracy
- `instrumental`: Optimized for instrumental tracks
Default: `base`
enum:
- base
- enhanced
- instrumental
example: base
output_type:
type: string
description: |-
Type of output stems to generate.
- `general`: All available stems (default)
- `bass`: Bass track only
- `drums`: Drums track only
- `other`: Other instruments
- `piano`: Piano track only
- `guitar`: Guitar track only
- `vocals`: Vocals track only
Default: `general`
enum:
- general
- bass
- drums
- other
- piano
- guitar
- vocals
example: general
SubmitResponse:
type: object
required:
- code
- data
properties:
code:
type: integer
example: 200
description: HTTP status code
data:
type: object
required:
- task_id
- status
- created_time
properties:
task_id:
type: string
example: task-unified-1757165031-uyujaw3d
description: Unique task identifier for status tracking
status:
type: string
enum:
- not_started
example: not_started
description: Initial task status
created_time:
type: string
format: date-time
example: '2025-11-12T10:30:00'
description: ISO 8601 timestamp when the task was created
ErrorResponse:
type: object
required:
- code
- error
properties:
code:
type: integer
example: 400
description: HTTP status code
error:
type: object
required:
- message
- type
properties:
message:
type: string
example: Invalid request parameters
description: Error message describing what went wrong
type:
type: string
example: invalid_request_error
description: Error type identifier
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
All API endpoints require Bearer Token authentication
Get your API Key:
Visit the [API Key Management
Page](https://vidgo.ai/apis/dashboard/api-key) to get your API Key
Add it to the request header:
```
Authorization: Bearer VIDGO_API_KEY
```
````