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

# Audio Mastering

> Processes an input audio file to match the mastering characteristics of a reference track.

Master your audio files professionally using a reference track.

**Audio Mastering** uses intelligent processing to match the sonic quality of your track to a reference file — perfect for music production, podcasts, and post-production work.

* Match tone, loudness, and clarity
* Supports formats like MP3, WAV, FLAC, and more
* Quick, accurate mastering with webhook support

***

## Endpoint

```http theme={null}
POST /audio_mastering
```

Use this endpoint to master an audio file based on a reference track.

***

## Sample Output

Listen to the mastered audio:

<audio controls="1" controlslist="nodownload nofullscreen noremoteplayback" src="https://musicgpt.s3.us-east-1.amazonaws.com/conversions/sample-mastered.mp3">Your browser does not support audio playback.</audio>

***

## Try it Yourself

Visit the [Audio Mastering Endpoint Explorer](/api-documentation/endpoint/audio_mastering) to upload an audio and reference track for instant mastering.

> Tip: Use a professionally mastered song as your reference for best results!

***

## Request Parameters

| Parameter              | Type   | Required | Description                                                        |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------ |
| `audio_path`           | String | Yes      | URL path of the input audio file to be mastered                    |
| `conversion_id`        | String | Yes      | Unique identifier for this conversion request                      |
| `reference_audio_path` | String | Yes      | URL path of the reference audio file to match                      |
| `output_extension`     | String | Optional | Desired output format (`mp3`, `wav`, `flac`, `ogg`, `aac`, `webm`) |
| `audio_duration`       | Float  | Yes      | Duration of input audio in seconds (for credit calculation)        |
| `webhook_url`          | String | Optional | URL to receive callback notification when processing completes     |
| `user_id`              | String | Optional | User ID for tracking (from authentication token)                   |

> **content-type:** multipart/form-data

***

## Sample Request

### Python

```python theme={null}
import requests

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

# Option 1: Using URLs
payload = {
    "audio_url": "https://example.com/input_audio.mp3",
    "reference_audio_url": "https://example.com/reference_track.wav",
    "output_extension": "wav",
    "webhook_url": "http://your-webhook-url.com/callback"
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())

# Option 2: Upload files
# with open("input.mp3", "rb") as input_file, open("ref.wav", "rb") as ref_file:
#     files = {
#         "audio_file": input_file,
#         "reference_audio_file": ref_file
#     }
#     data = {
#         "output_extension": "wav",
#         "webhook_url": "http://your-webhook-url.com/callback"
#     }
#     response = requests.post(url, headers=headers, files=files, data=data)
#     print(response.json())
```

***

## Sample Response

### Success (200 OK)

```json theme={null}
{
  "success": true,
  "task_id": "0d12ef34-5678-4abc-9123-456def7890ab",
  "conversion_id": "user_master_12345",
  "credit_estimate": 0.02,
  "eta": 120,
  "message": "Mastering request accepted"
}
```

***

## Webhook Response

If a `webhook_url` is provided, you will receive the following once processing completes:

```json theme={null}
{
  "success": true,
  "task_id": "0d12ef34-5678-4abc-9123-456def7890ab",
  "conversion_id": "user_master_12345",
  "conversion_path": "https://musicgpt.s3.us-east-1.amazonaws.com/conversions/sample-mastered.mp3",
  "credit_cost": 0.02
}
```

> 📂 If no webhook is provided, you can fetch the final mastered audio manually later using the `conversion_id`.

***

## Payload and Request Formation


## OpenAPI

````yaml POST /v1/audio_mastering
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/audio_mastering:
    post:
      summary: Master an audio file using a reference track
      description: >-
        Processes an input audio file to match the mastering characteristics of
        a reference track.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                audio_url:
                  type: string
                  description: URL of the input audio to be processed.
                  example: https://example.com/input_audio.mp3
                audio_file:
                  type: string
                  format: binary
                  description: Input audio file to upload directly.
                reference_audio_url:
                  type: string
                  description: URL of the reference audio file to match.
                  example: https://example.com/reference_track.wav
                reference_audio_file:
                  type: string
                  format: binary
                  description: Reference audio file to upload directly.
                output_extension:
                  type: string
                  enum:
                    - mp3
                    - wav
                    - flac
                    - ogg
                    - aac
                    - webm
                  description: Desired output file format.
                  example: wav
                webhook_url:
                  type: string
                  description: Callback URL to receive async result.
                  example: http://your-webhook-url.com/callback
              anyOf:
                - required:
                    - audio_url
                    - reference_audio_url
                - required:
                    - audio_file
                    - reference_audio_file
      responses:
        '200':
          description: Successfully queued for mastering
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  task_id:
                    type: string
                  conversion_id:
                    type: string
                  credit_estimate:
                    type: number
                    format: float
                  eta:
                    type: integer
                  message:
                    type: string
                example:
                  success: true
                  task_id: master123
                  conversion_id: conv456
                  credit_estimate: 150.75
                  eta: 300
                  message: Mastering task queued successfully
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Invalid output format specified
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Authentication failed
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Insufficient credits for this operation
                  required_credits:
                    type: number
                    example: 150.75
                  available_credits:
                    type: number
                    example: 100
        '404':
          description: User or plan not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: User subscription plan not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal server error during mastering
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            import requests


            url = "https://api.musicgpt.com/api/public/v1/audio_mastering"

            headers = {"Authorization": "<<<api key>>>"}


            # Option 1: Using URLs

            payload = {
                "audio_url": "https://example.com/input_audio.mp3",
                "reference_audio_url": "https://example.com/reference_track.wav",
                "output_extension": "wav",
                "webhook_url": "http://your-webhook-url.com/callback"
            }

            response = requests.post(url, headers=headers, data=payload)

            print(response.json())


            # Option 2: Upload files

            # with open("input.mp3", "rb") as input_file, open("ref.wav", "rb")
            as ref_file:

            #     files = {

            #         "audio_file": input_file,

            #         "reference_audio_file": ref_file

            #     }

            #     data = {

            #         "output_extension": "wav",

            #         "webhook_url": "http://your-webhook-url.com/callback"

            #     }

            #     response = requests.post(url, headers=headers, files=files,
            data=data)

            #     print(response.json())
        - lang: PHP
          source: |-
            <?php
            $url = 'https://api.musicgpt.com/api/public/v1/audio_mastering';
            $headers = ['Authorization: <<<api key>>>'];

            // Option 1: URL mode
            $data = [
                'audio_url' => 'https://example.com/input_audio.mp3',
                'reference_audio_url' => 'https://example.com/reference_track.wav',
                'output_extension' => 'wav',
                'webhook_url' => 'http://your-webhook-url.com/callback'
            ];
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            $response = curl_exec($ch);
            curl_close($ch);
            echo $response;

            // Option 2: File Upload
            // $data = [
            //     'audio_file' => new CURLFile('input.mp3'),
            //     'reference_audio_file' => new CURLFile('ref.wav'),
            //     'output_extension' => 'wav',
            //     'webhook_url' => 'http://your-webhook-url.com/callback'
            // ];
            // $ch = curl_init($url);
            // curl_setopt($ch, CURLOPT_POST, true);
            // curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
            // curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
            // curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            // $response = curl_exec($ch);
            // curl_close($ch);
            // echo $response;
        - lang: Go
          source: "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\turl := \"https://api.musicgpt.com/api/public/v1/audio_mastering\"\n\ttoken := \"<<<api key>>>\"\n\tdata := \"audio_url=https://example.com/input_audio.mp3&reference_audio_url=https://example.com/reference_track.wav&output_extension=wav&webhook_url=http://your-webhook-url.com/callback\"\n\n\treq, _ := http.NewRequest(\"POST\", url, strings.NewReader(data))\n\treq.Header.Add(\"Authorization\", token)\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\tfmt.Println(string(body))\n}"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````