Skip to main content
POST
/
file_convert
Python
import requests

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

# Option 1: URL
payload = {
    "audio_url": "https://example.com/audio.mp3",
    "target_format": "wav",
    "target_sr": 44100,
    "webhook_url": "https://your-webhook-url.com/callback"
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())

# Option 2: File Upload
# payload = {
#     "target_format": "flac",
#     "target_bit_depth": 24,
#     "webhook_url": "https://your-webhook-url.com/callback"
# }
# with open("audio.mp3", "rb") as f:
#     files = {"audio_file": f}
#     response = requests.post(url, headers=headers, data=payload, files=files)
# print(response.json())
{
  "success": true,
  "task_id": "convert789",
  "conversion_id": "conv456",
  "output_path": "https://storage.example.com/converted/audio.wav",
  "credit_estimate": 100.1
}
Convert audio files to different formats with optional webhook support for asynchronous updates.

​
Endpoint

POST /file_convert
This endpoint processes an uploaded or linked audio file and converts it to a specified output format. You may also define optional parameters like sample rate and bit depth.

​
Request Parameters

ParameterTypeRequiredDescription
audio_urlStringOptionalThe URL of an audio file to convert. Either audio_url or audio_file must be provided.
audio_fileUploadFileOptionalUpload the audio file directly. Either audio_url or audio_file must be provided.
target_formatStringYesDesired output format. Supported: mp3, wav, flac, ogg, aac, webm.
target_srIntegerOptionalTarget sample rate in Hz. Defaults to original if not specified.
target_bit_depthIntegerOptionalTarget bit depth. Options: 16, 24, 32. Defaults to 16.
webhook_urlStringOptionalCallback URL to receive the result once conversion is complete.
content-type: multipart/form-data

​
Sample Output

Listen to a real sample output: Download Audio

​
Try it Yourself

Visit the File Conversion Endpoint Explorer to try your own text samples.
💡 Tip: Set a webhook_url to receive results automatically when your audio is ready.

​
Sample Request

​
cURL

curl -X POST \
  -F "audio_file=@input.mp3" \
  -F "target_format=wav" \
  -F "target_sr=44100" \
  -F "webhook_url=https://yourdomain.com/webhook" \
  https://api.musicgpt.com/api/public/v1/convert

​
Python

import requests

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

# Option 1: URL
payload = {
    "audio_url": "https://example.com/audio.mp3",
    "target_format": "wav",
    "target_sr": 44100,
    "webhook_url": "https://your-webhook-url.com/callback"
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())

# Option 2: File Upload
# payload = {
#     "target_format": "flac",
#     "target_bit_depth": 24,
#     "webhook_url": "https://your-webhook-url.com/callback"
# }
# with open("audio.mp3", "rb") as f:
#     files = {"audio_file": f}
#     response = requests.post(url, headers=headers, data=payload, files=files)
# print(response.json())
🔐 Replace {path_to_your_audio_file}, api_key, and webhook_url before executing.

​
Sample Response

​
Success (200 OK)

{
  "success":true,
  "task_id":"7024eac0-02e2-4811-96e3-7031f007f97f",
  "conversion_id":"a1286a84-d886-47d9-a717-77af15894cb9",
  "eta":-1,
  "credit_estimate":19.833,
  "message":"",
  "status":"IN_QUEUE"
}

​
Webhook Response

​
Success (200 OK)

{
  "success": true, 
  "conversion_id": "a1286a84-d886-47d9-a717-77af15894cb9", 
  "output_file_path": "https://lalals.s3.us-east-1.amazonaws.com/FileConversions/059ab1ef-c92d-4be4-b2f3-4fe57d26ae87.mp3", 
  "conversion_type": "File Conversion", 
  "task_id": "7024eac0-02e2-4811-96e3-7031f007f97f"
}

​
Common Errors

  • 400 Bad Request: Invalid request. Possibly due to missing parameters or unsupported formats.
  • 500 Internal Server Error: Server encountered an error during processing.

​
Webhook Response

Once the file conversion is completed, the webhook receives: 
{
  "success": true,
  "conversion_id": "teststagetestapril26",
  "output_file_path": "https://musicgpt.s3.amazonaws.com/conversions/123abc-denoise_no_noise.mp3",
  "conversion_type": "File Conversion"
}

​
Output Fields

  • output_file_path: Direct URL to download the converted audio file.
  • conversion_type: Always File Conversion for this endpoint.
  • conversion_id: A unique ID to track the request status.

Authorizations

​
Authorization
string
header
required

Body

multipart/form-data
  • Option 1
  • Option 2
​
audio_url
string
required

URL of the audio file to convert

Example:

"https://example.com/audio.mp3"

​
target_format
enum<string>
required

Target format for conversion

Available options:
mp3,
wav,
flac,
ogg,
aac,
webm
Example:

"wav"

​
audio_file
file

Audio file to upload and convert directly

​
target_sr
enum<integer>
default:44100

Target sample rate in Hz (optional) - can be any of [8000, 16000, 22050, 24000, 32000, 44100, 48000, 96000, 192000]

Available options:
8000,
16000,
22050,
24000,
32000,
44100,
48000,
96000,
192000
Example:

44100

​
target_bit_depth
enum<integer>

Target bit depth (16, 24, or 32)

Available options:
16,
24,
32
Example:

24

​
webhook_url
string

Callback URL for async processing results

Example:

"https://your-webhook-url.com/callback"

Response

Successfully initiated file conversion

​
success
boolean
​
task_id
string
​
conversion_id
string
​
output_path
string
​
credit_estimate
number