Extraction

Stem preset (free in November)

curl -X POST "https://api.musicgpt.com/api/public/v2/Extraction" \
-H "Authorization: <API_KEY>" \
-F "audio_url=<YOUR_AUDIO_URL>" \
-F "stem_preset=6_stems" \
-F "webhook_url=https://example.com/webhook"

import requests
import json

url = "https://api.musicgpt.com/api/public/v2/Extraction"

headers = {
    "Authorization": "<API_KEY>"
}

data = {
    "stems": json.dumps(["vocals", "drums"]),
    "preprocessing_options": json.dumps(["Denoise"]),
    "eco_mode": False,
    "webhook_url": "https://example.com/my-webhook"
}

# Option 1: audio_url
data["audio_url"] = "<YOUR_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())

const form = new FormData();
form.append('audio_url', '<string>');
form.append('audio_file', '<string>');
form.append('stem_preset', '6_stems');
form.append('stems', '["vocals", "drums"]');
form.append('preprocessing_options', '["Denoise", "Dereverb"]');
form.append('eco_mode', 'false');
form.append('webhook_url', 'http://webhook.musicgpt.com');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.musicgpt.com/api/public/v2/Extraction', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.musicgpt.com/api/public/v2/Extraction",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.musicgpt.com/api/public/v2/Extraction"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.musicgpt.com/api/public/v2/Extraction")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.musicgpt.com/api/public/v2/Extraction")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "task_id": "98bb0a78-854b-4ca7-a145-834c1ac73901",
  "conversion_id": "7c38aa60-e0c8-4113-983a-f2c6d4e6d257",
  "eta": 57,
  "credit_estimate": 0,
  "message": "Message published to queue",
  "status": "IN_QUEUE",
  "is_free_promo": true,
  "free_generations_remaining_hour": 14,
  "free_generations_remaining_day": 94,
  "free_quota_resets_at": "2026-11-03T15:00:00Z"
}

{
  "success": false,
  "error_code": "INSUFFICIENT_CREDITS",
  "message": ""
}

{
  "success": false,
  "error_code": "UNPROCESSABLE_CONTENT",
  "message": ""
}

{
  "success": false,
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": ""
}

POST

Extraction

Stem preset (free in November)

curl -X POST "https://api.musicgpt.com/api/public/v2/Extraction" \
-H "Authorization: <API_KEY>" \
-F "audio_url=<YOUR_AUDIO_URL>" \
-F "stem_preset=6_stems" \
-F "webhook_url=https://example.com/webhook"

import requests
import json

url = "https://api.musicgpt.com/api/public/v2/Extraction"

headers = {
    "Authorization": "<API_KEY>"
}

data = {
    "stems": json.dumps(["vocals", "drums"]),
    "preprocessing_options": json.dumps(["Denoise"]),
    "eco_mode": False,
    "webhook_url": "https://example.com/my-webhook"
}

# Option 1: audio_url
data["audio_url"] = "<YOUR_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())

const form = new FormData();
form.append('audio_url', '<string>');
form.append('audio_file', '<string>');
form.append('stem_preset', '6_stems');
form.append('stems', '["vocals", "drums"]');
form.append('preprocessing_options', '["Denoise", "Dereverb"]');
form.append('eco_mode', 'false');
form.append('webhook_url', 'http://webhook.musicgpt.com');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.musicgpt.com/api/public/v2/Extraction', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.musicgpt.com/api/public/v2/Extraction",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.musicgpt.com/api/public/v2/Extraction"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.musicgpt.com/api/public/v2/Extraction")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.musicgpt.com/api/public/v2/Extraction")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stem_preset\"\r\n\r\n6_stems\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"stems\"\r\n\r\n[\"vocals\", \"drums\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"preprocessing_options\"\r\n\r\n[\"Denoise\", \"Dereverb\"]\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eco_mode\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttp://webhook.musicgpt.com\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "task_id": "98bb0a78-854b-4ca7-a145-834c1ac73901",
  "conversion_id": "7c38aa60-e0c8-4113-983a-f2c6d4e6d257",
  "eta": 57,
  "credit_estimate": 0,
  "message": "Message published to queue",
  "status": "IN_QUEUE",
  "is_free_promo": true,
  "free_generations_remaining_hour": 14,
  "free_generations_remaining_day": 94,
  "free_quota_resets_at": "2026-11-03T15:00:00Z"
}

{
  "success": false,
  "error_code": "INSUFFICIENT_CREDITS",
  "message": ""
}

{
  "success": false,
  "error_code": "UNPROCESSABLE_CONTENT",
  "message": ""
}

{
  "success": false,
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": ""
}

No Cost November Nov 1 – Nov 30 (UTC)

Split everything, pay nothing

Throughout November, every extraction you send with stem_preset is free on paid plans. Pick 2_stems or 6_stems and pull vocals, instrumental, drums, bass, piano, and guitar out of any track at no cost.

$0per preset request

20free stems/ hour

100free stems / day

6stems per request

Read the integration guide →Get your API Key

Applies to requests that use stem_preset from paid plans. Requests that list stems, Free plan requests, and requests past the hourly or daily limit are charged at the usual stem splitter rates.

Extract vocals, instrumentals, or other stems from an audio file or URL, with optional preprocessing.

Endpoint

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	YouTube link of the track. For any other audio, send `audio_file`. Either `audio_url` or `audio_file` must be provided.
`audio_file`	`File`	Optional	Audio file to upload and process. For a file hosted at a URL, download it and upload it here. Either `audio_url` or `audio_file` must be provided.
`stem_preset`	`string`	Optional	Quick preset instead of `stems`: `2_stems` or `6_stems`. See Stem presets. Free on paid plans in November 2026.
`stems`	`string`	Optional	JSON string list of required stems. e.g., `["vocals", "drums"]`. Required unless you send `stem_preset`. 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.

Max input audio length: 8 minutes. See Audio Length Limits.

Note: Either audio_file or audio_url must be provided, and either stems or stem_preset, not both.

content-type: multipart/form-data

Stem presets

Use stem_preset to request a common split without listing stems. The preset replaces stems, so leave stems out or send [].

`stem_preset`	Stems you get back	Good for
`2_stems`	`vocals`, `instrumental`	Karaoke tracks, acapellas, vocal remixes
`6_stems`	`vocals`, `instrumental`, `piano`, `bass`, `drums`, `guitar`	Full band breakdowns, practice tracks, sampling

You can combine a preset with preprocessing_options and eco_mode. The webhook returns one URL per stem, exactly as a stems request does.

Free in November 2026. From Nov 1 00:00 to Nov 30 23:59:59 UTC, preset requests from paid plans are free, up to 20 stems per clock hour and 100 stems per day (UTC). The response tells you whether a request was free and how many free stems you have left. See the free stem presets guide to get the most out of it.

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: Without a stem_preset, stems must contain at least one stem. An omitted or empty stems list returns 422.

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 : Instrumental

Download Audio

Sample Request

cURL with a stem preset

Free on paid plans during November 2026. Upload the track as audio_file, or send a YouTube link as audio_url.

curl -X POST "https://api.musicgpt.com/api/public/v2/Extraction" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-F "audio_file=@song.mp3" \
-F "stem_preset=6_stems" \
-F "webhook_url=https://example.com/webhook"

curl -X POST "https://api.musicgpt.com/api/public/v2/Extraction" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-F "audio_url=https://www.youtube.com/watch?v=<VIDEO_ID>" \
-F "stem_preset=6_stems" \
-F "webhook_url=https://example.com/webhook"

cURL with a stems list

curl -X POST "https://api.musicgpt.com/api/public/v2/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=https://example.com/webhook"

Python

import requests
import json

url = "https://api.musicgpt.com/api/public/v2/Extraction"

headers = {
    "Authorization": "<API_KEY>"
}

data = {
    "stems": json.dumps(["vocals", "drums"]),
    # Or use a preset instead of "stems" (free on paid plans in November 2026):
    # "stem_preset": "2_stems",
    "preprocessing_options": json.dumps(["Denoise"]),
    "eco_mode": False,
    "webhook_url": "https://example.com/my-webhook"
}

# Option 1: audio_url, for YouTube links
data["audio_url"] = "https://www.youtube.com/watch?v=<VIDEO_ID>"
response = requests.post(url, headers=headers, data=data)

# Option 2: upload a local file as audio_file
# with open("song.mp3", "rb") as f:
#     files = {"audio_file": f}
#     response = requests.post(url, headers=headers, data=data, files=files)

# Option 3: a file hosted at a URL: download it, then upload it as audio_file
# download = requests.get("https://example.com/song.mp3", timeout=120)
# download.raise_for_status()
# files = {"audio_file": ("song.mp3", download.content)}
# response = requests.post(url, headers=headers, data=data, files=files)

print(response.json())

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": 0.09,
  "message": "Message published to queue",
  "status": "IN_QUEUE",
  "is_free_promo": false,
  "free_generations_remaining_hour": null,
  "free_generations_remaining_day": null,
  "free_quota_resets_at": null
}

Success, free under the November promotion (200 OK)

{
  "success": true,
  "task_id": "5b0e6f1c-2d7a-4f63-9a51-3c8e2b7d9f10",
  "conversion_id": "a41c9e57-0b3d-4c2e-8f6a-7d1e5b2c9a84",
  "eta": 147,
  "credit_estimate": 0.0,
  "message": "Message published to queue",
  "status": "IN_QUEUE",
  "is_free_promo": true,
  "free_generations_remaining_hour": 14,
  "free_generations_remaining_day": 94,
  "free_quota_resets_at": "2026-11-03T15:00:00Z"
}

Field	Type	Description
`credit_estimate`	`number`	Estimated cost of this conversion. `0.0` when it is free under a promotion.
`is_free_promo`	`boolean`	`true` when this conversion is free under an active promotion. No credits are charged.
`free_generations_remaining_hour`	`integer \| null`	Free stems you have left in the current UTC clock hour (a preset uses one per stem). `null` when no promotion applies to the request.
`free_generations_remaining_day`	`integer \| null`	Free stems you have left today (UTC). `null` when no promotion applies to the request.
`free_quota_resets_at`	`string \| null`	UTC time when more free stems become available: the next hour, or the next day once today has too few stems left for this preset. `null` when no promotion applies to the request.

Webhook Response

{
  "success": true,
  "conversion_type": "Extraction",
  "task_id": "985db57f-ba11-4d4b-adf4-a665c60da678",
  "conversion_id": "fa22221f-9fdf-4b1c-8b86-d101c1e72f3e",
  "audio_url": "{\"vocals\": \"https://cdn1.musicgpt.com/conversions/985db57f-ba11-4d4b-adf4-a665c60da678_vocals.mp3\", \"instrumental\": \"https://cdn1.musicgpt.com/conversions/985db57f-ba11-4d4b-adf4-a665c60da678_instrumental.mp3\"}",
  "audio_url_wav": "{\"vocals\": \"https://cdn1.musicgpt.com/conversions/985db57f-ba11-4d4b-adf4-a665c60da678_vocals.mp3\", \"instrumental\": \"https://cdn1.musicgpt.com/conversions/985db57f-ba11-4d4b-adf4-a665c60da678_instrumental.mp3\"}",
  "conversion_cost": 0.157,
  "conversion_duration": 170.6898866213152,
  "title": "Extraction"
}

Common Errors

402 Payment Required (INSUFFICIENT_CREDITS): Your credit balance is insufficient for a charged request.
422 Unprocessable Entity (UNPROCESSABLE_CONTENT): Neither audio_url nor audio_file is provided, stems is empty without a stem_preset, stem_preset is not 2_stems or 6_stems, or both stems and stem_preset are sent.
500 Internal Server Error (INTERNAL_SERVER_ERROR): A server-side error occurred.

See Handling Errors for the error response format and all error codes.

Payload and Request Formation

Authorizations

Authorization

string

header

required

Body

multipart/form-data

Option 1
Option 2

audio_url

string

required

Input audio URL (supported format: YouTube URL).

audio_file

file

Audio file to upload and process.

stem_preset

enum<string>

Quick preset instead of stems. 2_stems: vocals, instrumental. 6_stems: vocals, instrumental, piano, bass, drums, guitar. Do not send with a non-empty stems list. Free on paid plans during November 2026 (UTC), up to 20 stems per clock hour and 100 stems per day; each preset uses one slot per stem (2 or 6).

Available options:

2_stems,

6_stems

Example:

"6_stems"

stems

string

default:[]

JSON string list of required output stems. Required unless stem_preset is sent. 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\"]"

eco_mode

boolean

default:false

Enable eco mode for faster parallel extraction.

webhook_url

string

Callback URL for async processing.

Example:

"http://webhook.musicgpt.com"

Response

Successfully initiated stem extraction

success

boolean

task_id

string

conversion_id

string

eta

integer

credit_estimate

number

message

string

status

string

True when this extraction is free under an active promotion. credit_estimate is then 0.0 and no credits are charged.

free_generations_remaining_hour

integer | null

Free stems left in the current UTC clock hour, or null when no promotion applies.

free_generations_remaining_day

integer | null

Free stems left today (UTC), or null when no promotion applies.

free_quota_resets_at

string<date-time> | null

UTC time when more free stems become available, or null when no promotion applies.

API Documentation

Utilities

Resources

Keep in mind

Features

Sample Request Endpoints

Helper Endpoints

Conversion Endpoints

Endpoint

Request Parameters

Stem presets

Available Stems

Vocals

Guitar

Drums

Keys and Piano

Strings and Winds

Other Instruments

Full Band (Composite)

Preprocessing Options

Sample Output

Sample Request

cURL with a stem preset

cURL with a stems list

Python

Sample Response

Success (200 OK)

Success, free under the November promotion (200 OK)

Webhook Response

Common Errors

Payload and Request Formation

Authorizations

Body

Response

​Endpoint

​Request Parameters

​Stem presets

​Available Stems

​Vocals

​Guitar

​Drums

​Keys and Piano

​Strings and Winds

​Other Instruments

​Full Band (Composite)

​Preprocessing Options

​Sample Output

​Sample Request

​cURL with a stem preset

​cURL with a stems list

​Python

​Sample Response

​Success (200 OK)

​Success, free under the November promotion (200 OK)

​Webhook Response

​Common Errors

​Payload and Request Formation

Authorizations

Body

Response

Endpoint

Request Parameters

Stem presets

Available Stems

Vocals

Guitar

Drums

Keys and Piano

Strings and Winds

Other Instruments

Full Band (Composite)

Preprocessing Options

Sample Output

Sample Request

cURL with a stem preset

cURL with a stems list

Python

Sample Response

Success (200 OK)

Success, free under the November promotion (200 OK)

Webhook Response

Common Errors

Payload and Request Formation