> ## 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.

# 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.

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

```http theme={null}
POST /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`            | `UploadFile` | 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.      |
| `webhook_url`           | `string`     | Optional | Callback 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
<audio controls="1" controlslist="nodownload nofullscreen noremoteplayback" src="https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_vocals.mp3">Your browser does not support the audio playback.</audio>

<a href="https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_vocals.wav" target="_blank">Download Audio</a>

Sample Output : instrumentals
<audio controls="1" controlslist="nodownload nofullscreen noremoteplayback" src="https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_instrumental.mp3">Your browser does not support the audio playback.</audio>

<a href="https://lalals.s3.amazonaws.com/conversions/1683c35d-3990-4aac-98da-6847a6893893_instrumental.wav" target="_blank">Download Audio</a>

***

## Sample Request

### cURL

```bash theme={null}
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

```python theme={null}
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)

```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

### Success (200 OK)

```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://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


## OpenAPI

````yaml POST /v1/Extraction
openapi: 3.1.0
info:
  title: Musicgpt API
  version: 1.0.0
  description: API for retrieving conversion details by ID.
servers:
  - url: https://api.musicgpt.com/api/public
    description: Production server
security: []
paths:
  /v1/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: The URL of the audio file to process.
                  example: https://www.youtube.com/watch?v=jGflUbPQfW8
                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"]'
                webhook_url:
                  type: string
                  description: Callback URL for async processing.
                  example: http://webhook.musicgpt.com
              anyOf:
                - required:
                    - audio_url
                - required:
                    - audio_file
      responses:
        '200':
          description: Successfully initiated audio extraction
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  task_id:
                    type: string
                  conversion_id:
                    type: string
                  eta:
                    type: integer
                    description: Time in seconds to completion. -1 if unknown
                  credit_estimate:
                    type: number
                    format: float
                    description: Estimated credit cost
                example:
                  success: true
                  task_id: 62725d68-01e8-4c87-8fb0-298aa81c529c
                  conversion_id: 46b358c9-b22f-49d1-a68d-17901a6a549b
                  eta: 11
                  credit_estimate: 2.5
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    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
                  error:
                    type: string
                    example: Internal Server Error
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            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())
        - lang: PHP
          source: |-
            $curl = curl_init();

            $stems = json_encode(['vocals', 'drums']);
            $preprocessing = json_encode(['Denoise']);

            curl_setopt_array($curl, [
                CURLOPT_URL => 'https://api.musicgpt.com/api/public/v1/Extraction',
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => [
                    'audio_url' => '',
                    'stems' => $stems,
                    'preprocessing_options' => $preprocessing,
                    'webhook_url' => 'http://webhook.musicgpt.com',
                    'audio_file' => new CURLFile('path_to_audio.mp3')
                ],
                CURLOPT_HTTPHEADER => [
                    'Authorization: <API_KEY>',
                    'Accept: application/json'
                ]
            ]);

            $response = curl_exec($curl);
            curl_close($curl);

            echo $response;
        - lang: Go
          source: |-
            package main

            import (
                "bytes"
                "encoding/json"
                "fmt"
                "io"
                "mime/multipart"
                "net/http"
                "os"
            )

            func main() {
                body := &bytes.Buffer{}
                writer := multipart.NewWriter(body)

                file, _ := os.Open("path_to_audio.mp3")
                part, _ := writer.CreateFormFile("audio_file", "path_to_audio.mp3")
                io.Copy(part, file)
                
                stems, _ := json.Marshal([]string{"vocals", "drums"})
                preprocessing, _ := json.Marshal([]string{"Denoise"})
                
                writer.WriteField("stems", string(stems))
                writer.WriteField("preprocessing_options", string(preprocessing))
                writer.WriteField("webhook_url", "http://webhook.musicgpt.com")
                writer.Close()

                req, _ := http.NewRequest("POST", "https://api.musicgpt.com/api/public/v1/Extraction", body)
                req.Header.Add("Authorization", "<API_KEY>")
                req.Header.Add("Content-Type", writer.FormDataContentType())

                client := &http.Client{}
                resp, _ := client.Do(req)
                defer resp.Body.Close()

                responseBody, _ := io.ReadAll(resp.Body)
                fmt.Println(string(responseBody))
            }
        - lang: Java
          source: |-
            import okhttp3.*;
            import org.json.JSONArray;
            import java.io.File;
            import java.io.IOException;

            public class MusicgptExtraction {
                public static void main(String[] args) throws IOException {
                    OkHttpClient client = new OkHttpClient();

                    MediaType mediaType = MediaType.parse("audio/mpeg");
                    File file = new File("path_to_audio.mp3");

                    JSONArray stems = new JSONArray();
                    stems.put("vocals");
                    stems.put("drums");
                    
                    JSONArray preprocessing = new JSONArray();
                    preprocessing.put("Denoise");

                    RequestBody fileBody = RequestBody.create(file, mediaType);
                    RequestBody requestBody = new MultipartBody.Builder().setType(MultipartBody.FORM)
                        .addFormDataPart("audio_file", file.getName(), fileBody)
                        .addFormDataPart("stems", stems.toString())
                        .addFormDataPart("preprocessing_options", preprocessing.toString())
                        .addFormDataPart("webhook_url", "http://webhook.musicgpt.com")
                        .build();

                    Request request = new Request.Builder()
                        .url("https://api.musicgpt.com/api/public/v1/Extraction")
                        .post(requestBody)
                        .addHeader("Authorization", "<API_KEY>")
                        .addHeader("Accept", "application/json")
                        .build();

                    Response response = client.newCall(request).execute();
                    System.out.println(response.body().string());
                }
            }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````