Skip to main content
POST
/
Extraction
Python
import requests
import json

url = "https://api.musicgpt.com/api/public/v1/Extraction"
headers = {
    "Authorization": "<API_KEY>"
}

files = {
    "audio_file": open("path_to_audio.mp3", "rb")
}
data = {
    "audio_url": "",
    "stems": json.dumps(["vocals", "drums"]),
    "preprocessing_options": json.dumps(["Denoise"]),
    "webhook_url": "http://webhook.musicgpt.com"
}

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
{
  "success": true,
  "task_id": "62725d68-01e8-4c87-8fb0-298aa81c529c",
  "conversion_id": "46b358c9-b22f-49d1-a68d-17901a6a549b",
  "eta": 11,
  "credit_estimate": 2.5
}
Extract vocals, instrumentals, or other stems from an audio file or URL, with optional preprocessing. This endpoint supports file uploads or remote URLs and allows webhook callbacks for async updates.

​
Endpoint

POST /Extraction
Use this endpoint to extract stems like vocals, drums, guitar, or more from an audio source.

​
Request Parameters

ParameterTypeRequiredDescription
audio_urlstringOptionalURL of the audio file to extract from. Either audio_url or audio_file must be provided.
audio_fileUploadFileOptionalAudio file to upload and process. Either audio_url or audio_file must be provided.
stemsstringOptionalJSON string list of required stems. e.g., ["vocals", "drums"]. See all options below.
preprocessing_optionsstringOptionalJSON string list of preprocessing options. e.g., ["Denoise"]. See all options below.
webhook_urlstringOptionalCallback URL to receive async processing results.
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

curl -X POST "https://api.musicgpt.com/api/public/v1/Extraction" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-F "audio_file=@path_to_audio.mp3" \
-F "stems=[\"vocals\",\"drums\"]" \
-F "preprocessing_options=[\"Denoise\"]" \
-F "webhook_url=http://webhook.musicgpt.com"

​
Python

import requests
import json

url = "https://api.musicgpt.com/api/public/v1/Extraction"
headers = {
    "accept": "application/json",
    "Authorization": "<api_key>"
}

files = {
    "audio_file": open("path_to_audio.mp3", "rb")
}
data = {
    "audio_url": "",
    "stems": json.dumps(["vocals", "drums"]),
    "preprocessing_options": json.dumps(["Denoise"]),
    "webhook_url": "http://webhook.musicgpt.com"
}

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
🔐 Replace path_to_audio.mp3, api_key, and webhook_url with actual values.

​
Sample Response

​
Success (200 OK)

{
  "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

​
Success (200 OK)

{
  "success": true, 
  "conversion_type": "Extraction", 
  "task_id": "1683c35d-3990-4aac-98da-6847a6893893", 
  "conversion_id": "dded3f43-4715-4564-88e0-b66ebc00c466", 
  "audio_url": "{\"vocals\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_vocals.mp3\", 
                \"instrumental\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_instrumental.mp3\", 
                \"solo_guitar\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_solo_guitar.mp3\"}", 
  "audio_url_wav": "{\"vocals\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_vocals.wav\", 
                \"instrumental\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_instrumental.wav\", 
                \"solo_guitar\": \"https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_solo_guitar.wav\"}", 
  "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.
Download or stream individual stems from their respective URLs.

​
Payload and Request Formation

Authorizations

​
Authorization
string
header
required

Body

multipart/form-data
​
audio_url
string
required

The URL of the audio file to process.

Example:

"https://www.youtube.com/watch?v=jGflUbPQfW8"

​
audio_file
file

Audio file to upload and process.

​
stems
string
default:[]

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
string
default:[]

JSON string list of preprocessing steps. Available options: Denoise, Deecho, Dereverb.

Example:

"[\"Denoise\", \"Dereverb\"]"

​
webhook_url
string

Callback URL for async processing.

Example:

"http://webhook.musicgpt.com"

Response

Successfully initiated audio extraction

​
success
boolean
​
task_id
string
​
conversion_id
string
​
eta
integer

Time in seconds to completion. -1 if unknown

​
credit_estimate
number<float>

Estimated credit cost