> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wav.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Extraction
> Process an audio file to extract specified stems (vocals, instrumental, or other components) with optional preprocessing. Supports file upload or URL with webhook callback.
**Deprecation Notice:** Extraction v1 is still functional but has been deprecated. We recommend switching to the v2 endpoint for improved response times and better quality.
Extract vocals, instrumentals, or other stems from an audio file or URL, with optional preprocessing.
***
## Endpoint
```http theme={null}
POST /v2/Extraction
```
Use this endpoint to extract stems like vocals, drums, guitar, or more from an audio source.
***
## Request Parameters
| Parameter | Type | Required | Description |
| ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `audio_url` | `string` | Optional | URL of the audio file to extract from. Either `audio_url` or `audio_file` must be provided. |
| `audio_file` | `File` | Optional | Audio file to upload and process. Either `audio_url` or `audio_file` must be provided. |
| `stems` | `string` | Optional | JSON string list of required stems. e.g., `["vocals", "drums"]`. See all options below. |
| `preprocessing_options` | `string` | Optional | JSON string list of preprocessing options. e.g., `["Denoise"]`. See all options below. |
| `eco_mode` | `boolean` | Optional | Enable eco mode for faster parallel extraction. Default: `false`. |
| `webhook_url` | `string` | Optional | Callback URL to receive async processing results. |
> **Note:** Either audio\_file or audio\_url must be provided.
> **content-type:** multipart/form-data
***
## Available Stems
The following audio stems can be extracted. They are grouped into categories based on instrument type or function:
### Vocals
* `vocals` — All vocal content (combined)
* `male_vocal` — Male vocals only
* `female_vocal` — Female vocals only
* `lead_vocal` — Lead singer’s voice
* `back_vocal` — Backing vocals
### Guitar
* `guitar` — All guitar sounds
* `acoustic_guitar` — Acoustic guitar
* `electric_guitar` — Electric guitar
* `rhythm_guitar` — Rhythm guitar parts
* `solo_guitar` — Solo guitar parts
### Drums
* `drums` — All drum elements
* `kick_drum` — Kick or bass drum
* `snare_drum` — Snare drum
* `toms` — Tom drums
* `hi_hat` — Hi-hat cymbals
* `ride` — Ride cymbal
* `crash` — Crash cymbal
### Keys and Piano
* `piano` — Piano only
* `keys` — Keyboard instruments (includes synths, organs, etc.)
### Strings and Winds
* `strings` — String instruments (e.g., violin, cello)
* `winds` — Wind instruments (e.g., saxophone, flute)
### Other Instruments
* `bass` — Bassline instruments
* `instrumental` — All non-vocal content (used to get instrumental version)
### Full Band (Composite)
* `drums`, `bass`, `piano`, `guitar` — Common full-band instrumentation
> **Note:** If the `stems` parameter is omitted or an empty list is supplied, this full band composite (`["drums", "bass", "piano", "guitar"]`) is used as the default.
***
## Preprocessing Options
These preprocessing steps can be applied to the input audio before stem extraction:
* `Denoise` — Reduces ambient or background noise
* `Deecho` — Removes echo and early reflections
* `Dereverb` — Reduces late reverberation from recordings
***
## Sample Output
Sample Output : Vocals
Download Audio
Sample Output : instrumentals
Download Audio
***
## Sample Request
### cURL
```bash theme={null}
curl -X POST "https://api.wav.com/api/public/v1/Extraction" \
-H "accept: application/json" \
-H "Authorization: " \
-F "audio_file=@path_to_audio.mp3" \
-F "stems=[\"vocals\",\"drums\"]" \
-F "preprocessing_options=[\"Denoise\"]" \
-F "webhook_url=https://example.com/webhook"
```
### Python
```python theme={null}
import requests
import json
url = "https://api.wav.com/api/public/v2/Extraction"
headers = {
"Authorization": ""
}
data = {
"stems": json.dumps(["vocals", "drums"]),
"preprocessing_options": json.dumps(["Denoise"]),
"webhook_url": "https://example.com/my-webhook"
}
# Option 1: audio_url
data["audio_url"] = ""
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
```
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success":true,
"task_id":"1683c35d-3990-4aac-98da-6847a6893893",
"conversion_id":"dded3f43-4715-4564-88e0-b66ebc00c466",
"eta":147,
"credit_estimate":5.55,
"message":"Message published to queue",
"status":"IN_QUEUE"
}
```
***
## Webhook Response
```json theme={null}
{
"success": true,
"conversion_type": "Extraction",
"task_id": "1683c35d-3990-4aac-98da-6847a6893893",
"conversion_id": "dded3f43-4715-4564-88e0-b66ebc00c466",
"audio_url": "{\"vocals\": \"https://cdn1.wav.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_vocals.mp3\",
\"instrumental\": \"https://cdn1.wav.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_instrumental.mp3\",
\"solo_guitar\": \"https://cdn1.wav.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_solo_guitar.mp3\"}",
"conversion_cost": "5.55",
"conversion_duration": 136.83045351473922
}
```
***
## Common Errors
* **422 Unprocessable Entity**: When neither `audio_url` nor `audio_file` is provided.
* **500 Internal Server Error**: A server-side error occurred.
***
## Payload and Request Formation
## OpenAPI
````yaml POST /v2/Extraction
openapi: 3.1.0
info:
title: WAV API
version: 1.0.0
description: API for retrieving conversion details by ID.
servers:
- url: https://api.wav.com/api/public
description: Production server
security: []
paths:
/v2/Extraction:
post:
summary: Extract stems from an audio file or URL
description: >-
Process an audio file to extract specified stems (vocals, instrumental,
or other components) with optional preprocessing. Supports file upload
or URL with webhook callback.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
audio_url:
type: string
description: 'Input audio URL (supported format: YouTube URL).'
example: https://www.youtube.com/watch?v=example123
audio_file:
type: string
format: binary
description: Audio file to upload and process.
stems:
type: string
default: '[]'
description: >-
JSON string list of required output stems. Available
options: vocals, instrumental, male_vocal, female_vocal,
lead_vocal, back_vocal, bass, drums, guitar, piano, keys,
strings, winds, rhythm_guitar, solo_guitar, acoustic_guitar,
electric_guitar, kick_drum, snare_drum, toms, hi_hat, ride,
crash.
example: '["vocals", "drums"]'
preprocessing_options:
type: string
default: '[]'
description: >-
JSON string list of preprocessing steps. Available options:
Denoise, Deecho, Dereverb.
example: '["Denoise", "Dereverb"]'
eco_mode:
type: boolean
default: false
description: Enable eco mode for faster parallel extraction.
webhook_url:
type: string
description: Callback URL for async processing.
example: https://example.com/webhook
anyOf:
- required:
- audio_url
- required:
- audio_file
responses:
'200':
description: Successfully initiated stem extraction
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
task_id:
type: string
conversion_id:
type: string
eta:
type: integer
credit_estimate:
type: number
message:
type: string
status:
type: string
example:
success: true
task_id: 98bb0a78-854b-4ca7-a145-834c1ac73901
conversion_id: 7c38aa60-e0c8-4113-983a-f2c6d4e6d257
eta: 57
credit_estimate: 0.09
message: Message published to queue
status: IN_QUEUE
'422':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Either audio_url or audio_file must be provided.
'500':
description: Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Internal Server Error
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: Python
source: >-
import requests
import json
url = "https://api.wav.com/api/public/v2/Extraction"
headers = {
"Authorization": ""
}
data = {
"stems": json.dumps(["vocals", "drums"]),
"preprocessing_options": json.dumps(["Denoise"]),
"webhook_url": "https://example.com/my-webhook"
}
# Option 1: audio_url
data["audio_url"] = ""
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data,
files=files)
print(response.json())
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````