Skip to main content
POST
/
v1
/
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
}

Documentation Index

Fetch the complete documentation index at: https://docs.musicgpt.com/llms.txt

Use this file to discover all available pages before exploring further.

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