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



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

````