# Audio Cutter Source: https://docs.musicgpt.com/api-documentation/conversions/audiocutter POST /v1/audio_cutter Trims an audio file using the specified start and end times. **Audio Cutter** allows you to select specific sections of audio recordings, making it perfect for creating highlights, clips, ringtones, and more. * Easily extract the best parts of any audio * Supports multiple formats like MP3, WAV, FLAC, and more * Fast processing with high-quality output Audio Cutter ensures your trimmed audio sounds clean and professional. *** ## Endpoint ```http theme={null} POST /v1/audio_cutter ``` Use this endpoint to trim a section from an existing audio file. *** ## Sample Output Listen to the trimmed audio: Download Audio *** ## Try it Yourself Visit the [Audio Cutter Endpoint Explorer](/api-documentation/endpoint/audio_cutter) to cut and download trimmed audio segments instantly. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_file` | `File` | Optional | Upload the audio file. Required if `audio_url` is not provided. | | `audio_url` | `String` | Optional | URL to the audio file. | | `start_time` | Float | Yes | The start time (in milliseconds) of the audio to trim | | `end_time` | Float | Yes | The end time (in milliseconds) of the audio to trim | | `output_extension` | String | Yes | Output format: mp3, wav, flac, ogg, aac, or webm | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/audio_cutter" headers = {"Authorization": ""} payload = { "start_time": 10500, "end_time": 45000, "output_extension": "mp3" } # Option 1: audio_url payload["audio_url"] = "" response = requests.post(url, headers=headers, data=payload) # Option 2: File Upload # with open("input_audio.mp3", "rb") as f: # files = {"audio_file": f} # response = requests.post(url, headers=headers, data=payload, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"b0ac9d46-64d7-4843-af48-a0b6effe3666", "conversion_id":"fe19945b-d466-4183-b559-5d264bddd492", "eta":66, "credit_estimate":0.015, "message":"Message published to queue", "status":"IN_QUEUE" } ``` *** ## Webhook Response When audio cutter conversion completes, your webhook will receive: ```json theme={null} { "success": true, "conversion_type": "Audio Cutter", "task_id": "8993b364-9141-4de7-ab38-5a4178618f0e", "conversion_id": "3f07f1ba-9eb5-4581-95ed-427eac1dda0c", "output_file": "https://cdn1.musicgpt.com/conversions/6bfe2a8b-3076-490b-aec6-d1e5e6e59e83/6bfe2a8b-3076-490b-aec6-d1e5e6e59e83.mp3", "message": "Audio cutter completed", "title": "Audio Cutter" } ``` *** ## Payload and Request Formation # Audio Mastering Source: https://docs.musicgpt.com/api-documentation/conversions/audiomastering POST /v1/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 * Quick, accurate mastering with webhook support *** ## Endpoint ```http theme={null} POST /v1/audio_mastering ``` Use this endpoint to master an audio file based on a reference track. *** ## Sample Output Listen to the mastered audio: Download 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_file` | `File` | Optional | Upload the audio file directly. Required if `audio_url` is not provided. | | `reference_audio_file` | `File` | Optional | rReference audio file. | | `audio_url` | `String` | Optional | URL to the audio file. | | `reference_audio_url` | String | Optional | URL path of the reference audio file to match. | | `output_extension` | String | Optional | Desired output format (`mp3`, `wav`, `flac`, `ogg`, `aac`, `webm`) | | `webhook_url` | String | Optional | URL to receive callback notification when processing completes | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **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": "" } data = { "output_extension": "wav", "webhook_url": "https://example.com/my-webhook" } # Option 1: audio URLs data["audio_url"] = "" data["reference_audio_url"] = "" response = requests.post(url, headers=headers, data=data) # Option 2: File Upload # with open("song.mp3", "rb") as audio, open("reference.mp3", "rb") as reference: # files = { # "audio_file": audio, # "reference_audio_file": reference # } # response = requests.post(url, headers=headers, data=data, files=files) 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", "status": "IN_QUEUE" } ``` *** ## Webhook Response ```json theme={null} { "success": true, "conversion_type": "Audio Mastering", "task_id": "0d12ef34-5678-4abc-9123-456def7890ab", "conversion_id": "de7b2225-9a75-4315-b761-6dcc4357a8de", "output_file": "https://cdn1.musicgpt.com/conversions/de7425cd-8100-454e-b6fa-4673769e4507/de7425cd-8100-454e-b6fa-4673769e4507.mp3", "message": "Audio Mastering Completed", "title": "Audio Mastering" } ``` *** ## Payload and Request Formation # Audio Speed Changer Source: https://docs.musicgpt.com/api-documentation/conversions/audiospeedchanger POST /v1/audio_speed_changer Processes an audio file to change its playback speed based on a speed factor. Change the speed of your audio files without affecting quality. **Audio Speed Changer** allows you to easily speed up or slow down any audio file, perfect for creating remixes, practicing music, or adjusting spoken content. * Speed up or slow down audio effortlessly * Supports multiple formats like MP3, WAV, FLAC, and more * Fast processing with high-quality output *** ## Endpoint ```http theme={null} POST /v1/audio_speed_changer ``` Use this endpoint to adjust the speed of an audio file. *** ## Sample Output Listen to the speed-changed audio: *** ## Try it Yourself Visit the [Audio Speed Changer Endpoint Explorer](/api-documentation/endpoint/audio_speed_changer) to upload audio files and adjust their playback speed. > ⏩ Try different speed factors like 1.5x or 0.75x to test quality! *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_file` | `File` | Optional | Upload the audio file directly. Required if `audio_url` is not provided. | | `audio_url` | `String` | Optional | URL to the audio file. | | `speed_change_factor` | Number | Yes | Factor to change speed (e.g., 2.0 = double speed, 0.5 = half speed) (min: 0.25, max: 4.0) | | `output_extension` | String | Yes | Desired output format (`mp3`, `wav`, `flac`, `ogg`, `aac`, `webm`) | | `webhook_url` | String | Optional | URL to receive callback notification when processing completes | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/audio_speed_changer" headers = {"Authorization": ""} payload = { "speed_change_factor": 1.5, "output_extension": "mp3" } # Option 1: audio_url payload["audio_url"] = "" response = requests.post(url, headers=headers, data=payload) # Option 2: File Upload # with open("input_audio.mp3", "rb") as f: # files = {"audio_file": f} # response = requests.post(url, headers=headers, data=payload, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"b0ac9d46-64d7-4843-af48-a0b6effe3666", "conversion_id":"fe19945b-d466-4183-b559-5d264bddd492", "eta":66, "credit_estimate":0.15, "message":"Message published to queue", "status":"IN_QUEUE" } ``` *** ## Webhook Response When transcription completes, your webhook will receive: ```json theme={null} { "success": true, "conversion_type": "Audio Speed Changer", "task_id": "b0ac9d46-64d7-4843-af48-a0b6effe3666", "conversion_id": "fe19945b-d466-4183-b559-5d264bddd492", "output_file": "https://cdn1.musicgpt.com/conversions/e477a121-ba71-4753-96ae-874779f0623a/e477a121-ba71-4753-96ae-874779f0623a.mp3", "message": "Audio speed changer completed", "title": "Audio Speed Changer" } ``` *** ## Payload and Request Formation # Audio to MIDI Source: https://docs.musicgpt.com/api-documentation/conversions/audiotomidi POST /v1/audio_to_midi Processes an audio file and converts it into a MIDI file. Optionally generates a sonified .wav and/or a CSV of note events. This request is handled asynchronously. Convert an audio file into a MIDI file using AI-driven audio analysis and transcription. The **Audio to MIDI** endpoint processes audio files to generate MIDI sequences. It can optionally create a sonified `.wav` file of the MIDI output and export note events into a `.csv` file for further analysis or editing. Ideal for music production, remixing, and advanced audio content creation. *** ## Endpoint ```http theme={null} POST /v1/audio_to_midi ``` This is the primary endpoint for initiating audio-to-MIDI conversion tasks. *** ## Sample Output Generated MIDI and optional outputs from a sample audio file: Download MIDI(.mid) Download Sonified MIDI(.wav) *** ## Try it Yourself Visit the [Audio to MIDI Endpoint Explorer](/api-documentation/endpoint/audio_to_midi) to test it live. Upload an audio file, and get back the MIDI version! *** ## πŸ› οΈ Request Parameters | Parameter | Type | Required | Default | Description | | - | - | - | - | - | | `audio_file` | `File` | Optional | Upload the audio file directly. Required if `audio_url` is not provided. | | | `audio_url` | `String` | Optional | URL to the audio file. | | | `sonify_midi` | `Boolean` | Optional | `true` | If `true`, generates a `.wav` file that plays the MIDI output. | | `save_note_events` | `Boolean` | Optional | `true` | If `true`, saves predicted note events as a `.csv` file. | | `webhook_url` | `String` | Optional | `""` | Callback URL for asynchronous result delivery. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/audio_to_midi" \ -H "Authorization: " \ -F "audio_url=" \ -F "sonify_midi=true" \ -F "save_note_events=true" \ -F "webhook_url=https://your-webhook-url.com/callback" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/audio_to_midi" headers = {"Authorization": ""} payload = { "sonify_midi": True, "save_note_events": True, "webhook_url": "https://your-webhook-url.com/callback" } # Option 1: audio_url payload["audio_url"] = "" response = requests.post(url, headers=headers, data=payload) # Option 2: File Upload # with open("audio.wav", "rb") as f: # files = {"audio_file": f} # response = requests.post(url, headers=headers, data=payload, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "task_id": "cf34f4e0-3273-41e4-95e5-05dc745b9852", "conversion_id": "0b0b59e5-4c71-49ec-8ca5-5cd05142d5ab", "eta": 37, "credit_estimate": 0.016, "message": "Message published to queue", "status": "IN_QUEUE" } ``` *** ### Webhook Response ```json theme={null} { "success": true, "conversion_type": "Audio To MIDI", "task_id": "cf34f4e0-3273-41e4-95e5-05dc745b9852", "conversion_id": "0b0b59e5-4c71-49ec-8ca5-5cd05142d5ab", "midi_file_path": "", "sonify_file_path": "", "notes_file_path": "", "message": "Audio To MIDI Completed", "title": "Audio To MIDI" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Invalid request parameters. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): The conversion failed while processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Audio Transcribe Source: https://docs.musicgpt.com/api-documentation/conversions/audiotranscription POST /v1/audio_transcribe Processes an audio file to generate a transcription of the spoken content with support for language detection, translation, and multiple output formats. Convert your audio recordings into high-accuracy text using AI. **Audio Transcribe** enables seamless transcription for podcasts, interviews, lectures, meetings, and more. * Fast and accurate speech-to-text conversion * Supports multiple languages * Instant or asynchronous transcription with webhook support Audio Transcribe ensures reliable, professional-grade transcripts for your audio content. *** ## Endpoint ```http theme={null} POST /v1/audio_transcribe ``` Use this endpoint to transcribe audio recordings into text. *** ## Sample Output Transcript output for a short sample recording: > "Welcome to the show. Today we are talking about how machines learn to listen, and what that means for the music you hear every day. Let's get started." *** ## Try it Yourself Visit the [Audio Transcribe Endpoint Explorer](/api-documentation/endpoint/audiotranscribe) to upload audio files and get instant transcripts. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | String | Optional | URL to the audio file you want to transcribe. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `language` | String | Optional | Language code (e.g., `en`, `es`, `fr`) for targeted accuracy | | `webhook_url` | String | Optional | Webhook URL to receive the transcription asynchronously | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **content-type:** multipart/form-data > **Note:** Either audio\_file or audio\_url must be provided. *** ## Sample Request ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/audio_transcribe" headers = {"Authorization": ""} payload = { "language": "en", "translate": True, "transcription_format": "plain_text", "word_timestamps": True } # Option 1: audio_url payload["audio_url"] = "" response = requests.post(url, headers=headers, data=payload) # Option 2: File Upload # with open("audio.mp3", "rb") as f: # files = {"audio_file": f} # response = requests.post(url, headers=headers, data=payload, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"cade1dea-a9fb-49d3-a5b2-52f786ea5ad3", "conversion_id":"1c5a2543-5b99-499c-8bb4-28424497e60f", "eta":46, "credit_estimate":0.04, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response When transcription completes, your webhook will receive: ```json theme={null} { "success": true, "conversion_type": "Audio Transcription", "task_id": "cade1dea-a9fb-49d3-a5b2-52f786ea5ad3", "conversion_id": "1c5a2543-5b99-499c-8bb4-28424497e60f", "transcription": "Welcome to the show. Today we are talking about how machines learn to listen.", "translation": null, "detected_language": "en", "title": "Audio Transcription", "word_timestamps": [ { "index": 0, "text": "Welcome", "start": 0, "end": 420 }, { "index": 1, "text": "to", "start": 420, "end": 550 }, { "index": 2, "text": "the", "start": 550, "end": 680 }, { "index": 3, "text": "show", "start": 680, "end": 1010 } ] } ``` *** ## Payload and Request Formation # Cover Song Source: https://docs.musicgpt.com/api-documentation/conversions/cover POST /v1/Cover Convert an audio file or URL into a cover song using a different voice. Convert an audio file or URL into a cover song using a different voice model. The **Cover Song** endpoint recreates a vocal track using AI voice models, allowing for pitch manipulation and background audio transformation. Perfect for covers, remixes, or experimenting with different vocal styles. *** ## Endpoint ```http theme={null} POST /v1/Cover ``` This is the primary endpoint for initiating cover song conversion tasks. *** ## Sample Output Listen to a real sample output: Output File: Download Audio *** ## Try it Yourself Visit the [Cover Endpoint Explorer](/api-documentation/endpoint/cover) to test it live. Upload your audio, select a voice model, and hear the transformation. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | URL of the audio file to convert. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `UploadFile` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `voice_id` | `String` | Yes | Voice model to convert the audio into. | | `pitch` | `Integer` | Optional | Adjust pitch between -12 and 12 semitones. Default is `0`. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **content-type:** multipart/form-data *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/Cover" \ -H "accept: multipart/form-data" \ -H "Authorization: " \ -F "audio_url=" \ -F "voice_id=e0bb585f-b798-4bac-ac4e-de7fff38f9d7" \ -F "pitch=0" \ -F "webhook_url=https://webhook.musicgpt.com" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/Cover" headers = { "Authorization": "" } data = { "voice_id": "e0bb585f-b798-4bac-ac4e-de7fff38f9d7", "pitch": 0, "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "task_id": "3d137437-4911-4669-b639-9e5701107c25", "conversion_id": "b764b4f6-a842-42dd-a55b-818eb8251dc7", "eta": 71, "credit_estimate": 1.27, "message": "Message published to queue", "status": "IN_QUEUE" } ``` *** ## Webhook Response When the cover conversion completes, the webhook receives: ```json theme={null} { "success": true, "conversion_type": "Cover", "task_id": "0ec93bdd-6132-40db-a873-676dc314919c", "conversion_id": "acff300f-1c96-498d-99fe-929b985c5c55", "title": "Cover", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/d5c20c18-d505-5a1d-8c5f-5592c5941b97/d5c20c18-d505-5a1d-8c5f-5592c5941b97.mp3", "conversion_duration": 272.44, "message": "Conversion Completed" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Both `audio_url` and `audio_file` cannot be `None`. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): Something went wrong on our end. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Deecho Source: https://docs.musicgpt.com/api-documentation/conversions/deecho POST /v1/deecho Initiate an echo removal task using either an audio URL or file upload with optional webhook callback. Remove echo from input audio with optional webhook support for async updates. ## Endpoint ```http theme={null} POST /v1/deecho ``` This endpoint processes an audio file to reduce or eliminate echo effects. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | The URL of an audio file to remove echo from. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to a real sample output: Download Audio *** ## Try it Yourself Visit the [Deecho Endpoint Explorer](/api-documentation/endpoint/deecho) to try your own text samples. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/deecho" \ -H "Authorization: " \ -F "audio_url=" \ -F "webhook_url=https://example.com/my-webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/deecho" headers = { "Authorization": "" } data = { "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"938a071a-a5f5-40df-8eeb-972edcff26c4", "conversion_id":"e53b1bb5-381c-4e6f-844d-6a604002483c", "eta":59, "credit_estimate":0.48, "message":"Message published to queue", "status":"IN_QUEUE" } ``` *** ## Webhook Response ```json theme={null} { "success": true, "conversion_type": "Deecho", "task_id": "938a071a-a5f5-40df-8eeb-972edcff26c4", "conversion_id": "e53b1bb5-381c-4e6f-844d-6a604002483c", "audio_path": "files/8fd19e25-88c2-49e9-9641-7214cbe99a4f.wav", "no_echo": "https://cdn1.musicgpt.com/conversions/ce6dbeee-4195-4013-8be5-e1c3916d0994_no echo.mp3", "no_echo_wav": "", "echo": "https://cdn1.musicgpt.com/conversions/ce6dbeee-4195-4013-8be5-e1c3916d0994_echo.mp3", "message": "de_echo conversion Completed", "title": "Deecho", "conversion_duration": 136.82721088435375, "conversion_cost": "0.48" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Both `audio_url` and `audio_file` cannot be `None`. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): An error occurred on the server. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Denoise Source: https://docs.musicgpt.com/api-documentation/conversions/denoise POST /v1/denoise Initiate a noise removal task using either an audio URL or file upload with optional webhook callback. Remove background noise from an input audio file with optional webhook callback for asynchronous updates. *** ## Endpoint ```http theme={null} POST /v1/denoise ``` This endpoint removes noise from an uploaded or linked audio file. A `webhook_url` can be provided for asynchronous task status updates. *** ## Sample Output Listen to a real sample output: Download Audio *** ## Try it Yourself Visit the [Denoise Endpoint Explorer](/api-documentation/endpoint/denoise) to try your own text samples. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | The URL of an audio file to clean. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/denoise" \ -H "Authorization: " \ -F "audio_url=" \ -F "webhook_url=https://example.com/my-webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/denoise" headers = { "Authorization": "" } data = { "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"01e88c6d-5006-4ad9-b7c4-80360ca37860", "conversion_id":"c3f08613-998d-4ef9-80a9-9c05891e5237", "eta":71, "credit_estimate":0.48, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response ### Success (200 OK) ```json theme={null} { "success": true, "conversion_type": "Denoise", "task_id": "01e88c6d-5006-4ad9-b7c4-80360ca37860", "conversion_id": "c3f08613-998d-4ef9-80a9-9c05891e5237", "audio_path": "files/2e7c373c-aef9-4dda-8e70-2ff50ad18169.wav", "no_noise": "https://cdn1.musicgpt.com/conversions/12acc104-8156-47b5-8989-7e532495a2b9_dry.mp3", "noise": "https://cdn1.musicgpt.com/conversions/12acc104-8156-47b5-8989-7e532495a2b9_other.mp3", "noise_wav": "", "message": "de_noising conversion Completed", "title": "Denoise", "conversion_duration": 136.82721088435375, "conversion_cost": "0.48" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Both `audio_url` and `audio_file` cannot be `None`. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): A server error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Dereverb Source: https://docs.musicgpt.com/api-documentation/conversions/dereverb POST /v1/dereverb Initiate a reverberation removal task using either an audio URL or file upload with optional webhook callback. Remove reverb from an input audio file with optional webhook callback for asynchronous updates. *** ## Endpoint ```http theme={null} POST /v1/dereverb ``` This endpoint removes reverberation (echo) from an uploaded or linked audio file. A `webhook_url` can be provided for asynchronous task status updates. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | The URL of an audio file. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to a real sample output: Download Audio *** ## Try it Yourself Visit the [Dereverb Endpoint Explorer](/api-documentation/endpoint/dereverb) to try your own text samples. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/dereverb" \ -H "Authorization: " \ -F "audio_url=" \ -F "webhook_url=https://example.com/my-webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/dereverb" headers = { "Authorization": "" } data = { "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"e99d00bb-2ddf-4279-a15e-6e22801ee575", "conversion_id":"fbcf0c40-a33d-40aa-8c1d-7bb6f9df0b0f", "eta":40, "credit_estimate":0.48, "message":"Message published to queue", "status":"IN_QUEUE" } ``` *** ## Webhook Response ### Success (200 OK) ```json theme={null} { "success": true, "conversion_type": "Dereverb", "task_id": "e99d00bb-2ddf-4279-a15e-6e22801ee575", "conversion_id": "fbcf0c40-a33d-40aa-8c1d-7bb6f9df0b0f", "audio_path": "files/4efbdeff-48a2-401c-a9e6-8a2ffe465487.wav", "reverb": "https://cdn1.musicgpt.com/conversions/8df9c0f4-b673-495f-a9a0-715c366c0b55_reverb.mp3", "noreverb": "https://cdn1.musicgpt.com/conversions/8df9c0f4-b673-495f-a9a0-715c366c0b55_noreverb.mp3", "reverb_wav": "", "message": "de_reverb conversion Completed", "title": "Dereverb", "conversion_duration": 136.83045351473922, "conversion_cost": "0.48" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Both `audio_url` and `audio_file` cannot be `None`. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): A server error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** # Extend Source: https://docs.musicgpt.com/api-documentation/conversions/extend POST /v1/extend This endpoint allows users to extend an existing audio file or stream by appending new audio content after a specific timestamp. The new audio is generated using a prompt (e.g., describing the desired sound) and optional lyrics. Extend an existing audio file by generating new content after a specific timestamp. *** ## Endpoint ```http theme={null} POST /v1/extend ``` This endpoint allows users to extend an existing audio file or stream by appending new audio content after a specific timestamp. The new content is generated using a prompt and optional lyrics. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_file` | `File` | Optional | Upload the audio file to extend. Required if `audio_url` is not provided. | | `audio_url` | `String` | Optional | URL to the audio file. | | `extend_after` | `Float` | Required | Time (in seconds) after which new audio is generated. | | `prompt` | `String` | Optional | Describes the desired extension sound. Example: "Add a melodic flute section" | | `title` | `String` | Optional | Title of the generated music | | `lyrics` | `String` | Optional | Original lyrics of song. Max 3000 characters. | | `lyrics_section_to_extend` | `String` | Optional | Optional lyrics for the extended segment. Max 3000 characters. | | `gender` | `String` | Optional | Voice style if vocals are generated. Must be one of `male`, `female`, `neutral`. | | `num_outputs` | `int` | Optional | The number of outputs to generate (1 or 2 only, default : 2). | | `generate_album_cover` | Boolean | Optional | If `true`, generate an album cover for the generated audio | | `lyrics_timestamps` | Boolean | Optional | If true, generates lyric timestamps for the output track | | `webhook_url` | `String` | Optional | Callback URL for async result delivery. | > **Max input audio length:** 4 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to the extended audio. Prompt: loud drums sound - audio input : Rose and Bruno Mars - APT extend after: 6 Download Audio *** ## Try it Yourself Visit the [Extend Endpoint Explorer](/api-documentation/endpoint/extend) to play around - set your payload, hit send, and listen to the generated results live. *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests (non-instrumental): * Extend conversion details β€” one webhook per generated version, so `num_outputs` webhooks (default `2`) * Lyrics with timestamp data β€” one webhook per version, sent only when `lyrics_timestamps` is `true` * Album Cover Image β€” a single webhook, sent only when `generate_album_cover` is `true` > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/extend" \ -H "accept: application/json" \ -H "Authorization: " \ -F "audio_file=@/path/to/audio.mp3" \ -F "extend_after=35.0" \ -F "prompt=Add a calming piano outro" \ -F "lyrics=Let the journey fade away" \ -F "gender=neutral" \ -F "webhook_url=https://example.com/webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/extend" headers = {"Authorization": ""} data = { "extend_after": 35.0, "prompt": "Add a calming piano outro", "lyrics": "Let the journey fade away", "gender": "male", "lyrics_section_to_extend": "New_lyrics", "num_outputs": 2, "generate_album_cover": True, "lyrics_timestamps": True, "title": "My Generated Track", "webhook_url": "https://example.com/webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "message": "Extend request submitted successfully", "task_id": "a39f781f-e87e-4cbd-b923-aebf4aa451e6", "conversion_id_1": "f4ecf063-6ddd-43df-bc81-9eccea5b5042", "conversion_id_2": "49e99636-2ae7-4b5f-a907-e85a8fae95ad", "is_flagged": false, "reason": "", "eta": 199, "status": "IN_QUEUE", "credit_estimate": 0.12, "error_message": "", "error_message_detail": "", "missing_input_fields": "", "predicted_user_intent": "" } ``` *** ## Webhook Sample Payload Extend Webhook ```json theme={null} { "success": true, "conversion_type": "Extend", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "subtype": "remix" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Extend", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Extend", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Missing required fields like `extend_after`, or neither `audio_file` nor `audio_url` provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): An unexpected error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** The response provides a downloadable or streamable extended audio file. # Extraction Source: https://docs.musicgpt.com/api-documentation/conversions/extraction POST /v2/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. **Deprecation Notice:** Extraction v1 is still functional but has been deprecated. We recommend switching to the v2 endpoint for improved response times and better quality. Extract vocals, instrumentals, or other stems from an audio file or URL, with optional preprocessing. *** ## Endpoint ```http theme={null} 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 | URL of the audio file to extract from. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | 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. | | `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](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **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 Download Audio Sample Output : Instrumental Download Audio *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v2/Extraction" \ -H "accept: application/json" \ -H "Authorization: " \ -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/v2/Extraction" headers = { "Authorization": "" } data = { "stems": json.dumps(["vocals", "drums"]), "preprocessing_options": json.dumps(["Denoise"]), "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["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()) ``` *** ## 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 ```json theme={null} { "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. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): When neither `audio_url` nor `audio_file` is provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): A server-side error occurred. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Key & BPM Extraction Source: https://docs.musicgpt.com/api-documentation/conversions/extractkeybpm POST /v1/extract_key_bpm Processes an audio file to extract key changes, dominant key, and BPM (Beats Per Minute). Extract key and BPM (beats per minute) from an input audio file with optional webhook callback for asynchronous updates. *** ## Endpoint ```http theme={null} POST /v1/extract_key_bpm ``` This endpoint analyzes an audio file to determine its musical key and BPM. You can upload the audio file or provide a URL. Optionally, supply a `webhook_url` to receive asynchronous results. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | The URL of an audio file to analyze. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/extract_key_bpm" \ -H "accept: application/json" \ -H "Authorization: " \ -F "audio_url=" \ -F "webhook_url=https://example.com/my-webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/extract_key_bpm" headers = { "Authorization": "" } data = { "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["audio_url"] = "" # This endpoint expects multipart/form-data, so send the fields as form parts response = requests.post( url, headers=headers, files={k: (None, str(v)) for k, v in data.items()} ) # 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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"69ec90f0-a00a-48f8-bdb3-8728a635e057", "conversion_id":"8be8c439-dbc9-4ae6-8fe3-3fcb95f5a60a", "eta":-1, "credit_estimate":0.48, "message":"Successfully Published to Queue", "status":"IN_QUEUE" } ``` *** ## Webhook Response Once key and BPM extraction is completed, the webhook receives: ```json theme={null} { "success": true, "task_id": "69ec90f0-a00a-48f8-bdb3-8728a635e057", "conversion_id": "8be8c439-dbc9-4ae6-8fe3-3fcb95f5a60a", "audio_path": "https://cdn1.musicgpt.com/files/153ea693-aa7e-42cc-9e35-9a09cc011c4d.mp3", "conversion_duration": "0", "key_changes": {"0-120": ["A# major"], "120-140": ["D# major", "G minor"], "140-220": ["A# major", "A# minor"]}, "dominant_key": "A# major", "bpm": 162, "title": "Key BPM Extraction", "conversion_type": "Key BPM Extraction" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Both `audio_url` and `audio_file` cannot be `None`. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): A server error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Output Fields * `key_changes`: A mapping of time ranges to identified keys. * `dominant_key`: The most prominent key throughout the audio. * `bpm`: Estimated beats per minute. * `conversion_path`: Path to the original input audio file. * `conversion_path_wav`: Path to the `.wav` version of the input file. *** ## Payload and Request Formation # File Conversion Source: https://docs.musicgpt.com/api-documentation/conversions/fileconvert POST /v1/file_convert Initiate a file conversion task using either an audio URL or file upload with optional format parameters and webhook callback. Convert audio files to different formats with optional webhook support for asynchronous updates. *** ## Endpoint ```http theme={null} POST /v1/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 | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | The URL of an audio file to convert. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `target_format` | `String` | Yes | Desired output format. Supported: `mp3`, `wav`, `flac`, `ogg`, `aac`, `webm`. | | `target_sr` | `Integer` | Optional | Target sample rate in Hz. Defaults to original if not specified. | | `target_bit_depth` | `Integer` | Optional | Target bit depth. Options: `16`, `24`, `32`. Defaults to `16`. | | `webhook_url` | `String` | Optional | Callback URL to receive the result once conversion is complete. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **content-type:** multipart/form-data *** ## Sample Output Listen to a real sample output: Download Audio *** ## Try it Yourself Visit the [File Conversion Endpoint Explorer](/api-documentation/endpoint/fileconvert) to try your own text samples. *** ## Sample Request ### cURL ```bash theme={null} 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/file_convert ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/file_convert" headers = { "Authorization": "" } data = { "target_format": "wav", "target_sr": 44100, "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["audio_url"] = "" # This endpoint expects multipart/form-data, so send the fields as form parts response = requests.post( url, headers=headers, files={k: (None, str(v)) for k, v in data.items()} ) # 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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "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 ```json theme={null} { "success": true, "conversion_id": "a1286a84-d886-47d9-a717-77af15894cb9", "output_file_path": "https://cdn1.musicgpt.com/FileConversions/standard/3567f876-a196-467f-8538-f12ef1ba318e.mp3", "conversion_type": "File Conversion", "task_id": "7024eac0-02e2-4811-96e3-7031f007f97f", "title": "File Conversion", "message": "File conversion completed" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Invalid request. Possibly due to missing parameters or unsupported formats. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): Server encountered an error during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** # Image to Song Source: https://docs.musicgpt.com/api-documentation/conversions/imagetosong POST /v1/image_to_song Generate a song from an image by analyzing it and creating music based on visual content. The process can optionally include custom lyrics, voice conversion, and various musical parameters. Generate a song from an image by analyzing its content and creating music based on visual cues. Users can optionally provide custom lyrics, select a musical key, adjust tempo, or request instrumental/vocal-only outputs. *** ## Endpoint ```http theme={null} POST /v1/image_to_song ``` This endpoint processes an image (uploaded or via URL) to generate a song. The image is analyzed to create a descriptive prompt, which is then used to generate AI-driven music. ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `image_file` | `File` | Optional | Upload the image to analyze. Required if `image_url` is not provided. | | `image_url` | `String` | Optional | URL to the image file. Required if `image_file` is not provided. | | `prompt` | `String` | Optional | Additional text to guide the song generation (max 1000 characters). | | `lyrics` | `String` | Optional | Custom lyrics to include in the generated audio (max 5000 characters). | | `negative_tags` | `String` | Optional | Tags or themes to avoid in the song. | | `make_instrumental` | `Boolean` | Optional | If true, generates an instrumental version. Defaults to false. | | `vocal_only` | `Boolean` | Optional | If true, generates a vocal-only version. Defaults to false. | | `key` | `String` | Optional | Musical key for the song (e.g., "C major", "A minor"). | | `bpm` | `Integer` | Optional | Tempo in beats per minute. Defaults to 0 (auto-selected). | | `webhook_url` | `String` | Optional | Callback URL for async result delivery. | | `voice_id` | `String` | Optional | Voice ID for converting generated audio. Cannot be used with `vocal_only` mode. | > **Note:** Either image\_file or image\_url must be provided. > **content-type:** multipart/form-data *** ## Try it Yourself Visit the [image\_to\_song Endpoint Explorer](/api-documentation/endpoint/imagetosong) to play around β€” set your payload, hit send, and listen to the generated results live. ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/image_to_song" \ -H "accept: application/json" \ -H "Authorization: " \ -F "image_file=@/path/to/image.png" \ -F "prompt=Generate a relaxing acoustic track inspired by this scene." \ -F "lyrics=Let the colors of the sunset fill your heart." \ -F "make_instrumental=false" \ -F "vocal_only=false" \ -F "key=C major" \ -F "bpm=120" \ -F "webhook_url=https://example.com/webhook" \ -F "voice_id=voice_123" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/image_to_song" headers = {"Authorization": ""} data = { "prompt": "Generate a relaxing acoustic track inspired by this scene.", "lyrics": "Let the colors of the sunset fill your heart.", "make_instrumental": False, "vocal_only": False, "key": "C major", "bpm": 120, "webhook_url": "https://example.com/webhook", "voice_id": "voice_123" } # Option 1: image_url data["image_url"] = "" # This endpoint expects multipart/form-data, so send the fields as form parts response = requests.post( url, headers=headers, files={k: (None, str(v)) for k, v in data.items()} ) # Option 2: File Upload # with open("image.png", "rb") as f: # files = {"image_file": f} # response = requests.post(url, headers=headers, data=data, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "message": "Message Published To Queue", "task_id": "task-xyz-123", "conversion_id_1": "image-abc", "conversion_id_2": "image-def", "eta": 40, "credit_estimate": 45 } ``` *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests : * 2 (webhooks) x conversion details (one per version) * 2 (webhooks) x Lyrics with timestamp data * 1 Album Cover Image > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Neither `image_file` nor `image_url` provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): An unexpected error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** The response provides a downloadable audio file. *** # Inpaint Source: https://docs.musicgpt.com/api-documentation/conversions/inpaint POST /v1/inpaint This endpoint allows users to replace a specific time segment of an audio clip using a textual prompt and optional lyrics. The inpainting operation blends new audio content into the selected range, guided by user-defined style and voice preferences. To use the inpaint feature, upload a song and specify the lyrics you want to replace in the field **'lyrics_section_to_replace'**. For best results, also provide the complete song lyrics in the **lyrics**. Replace a specific segment of an audio file using a prompt and optional lyrics. *** ## Endpoint ```http theme={null} POST /v1/inpaint ``` This endpoint processes an input audio file along with a prompt, timestamp range, and optional lyrics to perform inpainting (replacement) in the specified segment. *** ## Request Parameters | Parameter | Type | Required | Description | | | - | - | - | - | - | | `audio_file` | `File` | Optional | Upload the input audio file. Required if `audio_url` is not provided. | | | `title` | `String` | Optional | Title of the generated music | | | `audio_url` | `String` | Optional | URL to the audio file. | | | `prompt` | `String` | Required | Prompt describing how the replacement should sound. Example: "Replace this part with an opera-style vocal." | | | `replace_start_at` | `Float` | Required | Start time (in seconds) of the segment to replace. | | | `replace_end_at` | `Float` | Required | End time (in seconds) of the segment to replace. | | | `lyrics` | `String` | Optional | Original lyrics of song. | | | `lyrics_section_to_replace` | `String` | Optional | Lyrics to be used for the replaced portion(optional, max 3000 characters) | | | `gender` | `String` | Optional | Voice style for vocal generation. One of: `male`, `female`, `neutral`. | | | `num_outputs` | `int` | Optional | The number of outputs to generate (1 or 2 only default : 2). | | | `generate_album_cover` | Boolean | Optional | If `true`, generate an album cover for the generated audio | | | `lyrics_timestamps` | Boolean | Optional | If true, generates lyric timestamps for the output track | | | `webhook_url` | `String` | Optional | Callback URL for async response. | | > **Max input audio length:** 4 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to a real output: Prompt: inpaint from 60 to 120 seconds in classical slow vibe - audio input : Moana How Far We will Go. Download Audio *** ## Try it Yourself Visit the [Inpaint Endpoint Explorer](/api-documentation/endpoint/inpaint) to test the endpoint - set your payload, hit send, and view the generated results. *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: ## Standard Requests: * 2 (webhooks) x Inpaint conversion details (one per version) * 2 (webhooks) x Lyrics with timestamp data * 1 Album Cover Image > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/inpaint" \ -H "accept: application/json" \ -H "Authorization: " \ -F "audio_file=@/path/to/audio.mp3" \ -F "prompt=Add a soft guitar solo here" \ -F "replace_start_at=12.5" \ -F "replace_end_at=20.0" \ -F "lyrics=This is where my story begins" \ -F "gender=male" \ -F "webhook_url=https://example.com/webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/inpaint" headers = {"Authorization": ""} data = { "prompt": "Add a soft guitar solo here", "replace_start_at": 12.5, "replace_end_at": 20.0, "lyrics": "This is where my story begins", "lyrics_section_to_replace": "New lyrics", "gender": "male", "num_outputs": 2, "generate_album_cover": True, "lyrics_timestamps": True, "title": "My Generated Track", "webhook_url": "https://example.com/webhook" } # Option 1: audio_url data["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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "message": "Inpaint request submitted successfully", "task_id": "070093dd-f1e9-4d7e-a6b3-ab6ecd237e38", "conversion_id_1": "7cac10af-9007-449f-b3ab-f60b05d23309", "conversion_id_2": "e85848c9-8feb-4cd8-85ef-456651a697b5", "is_flagged": false, "reason": "", "eta": 123, "status": "IN_QUEUE", "credit_estimate": 0.12, "error_message": "", "error_message_detail": "", "missing_input_fields": "", "predicted_user_intent": "" } ``` *** ## Webhook Sample Payload Inpaint Webhook ```json theme={null} { "success": true, "conversion_type": "Inpaint", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "subtype": "remix" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Inpaint", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Inpaint", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Missing required fields like `prompt`, `replace_start_at`, or `replace_end_at`, or neither `audio_file` nor `audio_url` provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): An unexpected error occurred during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Lyrics Generator Source: https://docs.musicgpt.com/api-documentation/conversions/lyrics_generator GET /v1/prompt_to_lyrics This endpoint takes a natural language prompt (e.g., a theme, vibe, or idea) and generates original lyrics based on it. If the prompt has been used before, a variation may be returned. It also estimates the credit cost of generation. ## Endpoint ```http theme={null} GET /v1/prompt_to_lyrics ``` *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `prompt` | `String` | βœ… Yes | The theme or idea you'd like lyrics generated for. | | | | | e.g., "A hopeful song about starting over" | > **Note:** The prompt must be between 1 and 1000 characters. *** ## Sample Request ### cURL ```bash theme={null} curl -G "https://api.musicgpt.com/api/public/v1/prompt_to_lyrics" \ --data-urlencode "prompt=A hopeful song about starting over" \ -H "Authorization: " \ -H "accept: application/json" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/prompt_to_lyrics" querystring = {"prompt":""} headers = {"Authorization": ""} response = requests.request("GET", url, headers=headers, params=querystring) print(response.text) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "title": null, "task_id": "0caa0bc2-d05a-414a-a730-a78e8e7f0b31", "lyrics": "[Verse 1]\nYou left ...", "music_style": null, "conversion_id": null, "message": "Lyrics Generated Successfully", "credit_estimate": 0.005 } ``` *** ## Use Case Examples * "A romantic song under the stars" * "A pop song about achieving your dreams" * "Grunge-style lyrics reflecting heartbreak" *** ## Output Generated lyrics are returned directly in the `lyrics` field of the response. They may be multi-paragraph and suited for use with vocal synthesis or songwriting tools. *** The `/prompt_to_lyrics` endpoint is ideal for songwriting, music composition tools, or creative text generation workflows. # Music AI Source: https://docs.musicgpt.com/api-documentation/conversions/musicai POST /v1/MusicAI Create music powered by AI using just a prompt, lyrics, or a defined music style. **Deprecation Notice:** Music AI v1 has been deprecated. Please use [Music AI v2](/api-documentation/conversions/musicaiv2) for the latest features, model selection (`v6`, `v6-pro`, `v7`, `v7-pro`), improved performance, and better output quality. **Music AI** generates original music compositions from a prompt, lyrics, or musical style. Whether you're a developer, content creator, or musician, this tool provides an easy and flexible way to create music powered by AI. Key features: * Compose custom songs using your own lyrics and chosen music style * Generate complete tracks from a single prompt, including lyrics, instrumentation, and melody * Apply voice conversion using a custom voice model * Output options: full tracks, instrumental-only, or vocal-only * Asynchronous webhook support for seamless integration Each request generates **two versions** of the song with variation, giving you more creative options. *** ## Endpoint ```http theme={null} POST /v1/MusicAI ``` *** ## Sample Output Listen to a real sample output: Prompt: a song about greenery, nature and forest. Download Audio *** ## Try It Yourself Use the [MusicAI Endpoint Explorer](/api-documentation/endpoint/MusicAI) to test your own requests using prompts, lyrics, and more. > Each request returns **two distinct versions** of the track. *** ## Request Parameters | Parameter | Type | Required | Default | Description | | - | - | - | - | - | | `prompt` | String | Optional | β€” | A natural language prompt for music generation | | `title` | String | Optional | β€” | Title of the generated music | | `music_style` | String | Optional | β€” | Musical style or genre (e.g., Rock, Pop, Lo-fi) | | `lyrics` | String | Optional | "" | Custom lyrics to use in the song | | `make_instrumental` | Boolean | Optional | false | If true, generate instrumental-only audio | | `vocal_only` | Boolean | Optional | false | If true, generate vocals without instruments | | `voice_id` | String | Optional | "" | Apply voice model for vocal rendering | | `webhook_url` | String | Optional | "" | URL to receive generated results via webhook | | `gender` | String | Optional | "" | Allowed values: male, female, neutral. | > **content-type:** application/json *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests (non-instrumental): * 2 (webhooks) x Music conversion details (one per version) * 2 (webhooks) x Lyrics with timestamp data * 1 (webhook ) x Album cover image #### Instrumental-only Requests: * 2 (webhook) x Music conversion details (one per version) * 1 (webhook) x Album cover image > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request (Python) ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/MusicAI" headers = { "Authorization": "", "Content-Type": "application/json" } payload = { "prompt": "Create a relaxing lo-fi song for studying", "lyrics": "It's a brand new day", "make_instrumental": False, "vocal_only": False, "title": "My Generated Track", "gender": "female", "generate_album_cover": False, "webhook_url": "https://example.com/my-webhook" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` *** ## Sample Response ```json theme={null} { "success": true, "message": "Message published to queue", "task_id": "50c04348-7077-5ffd-a407-55f031db20ef", "eta": 154, "conversion_id_1": "5a2c6385-e2e1-5531-a530-aab3ff040a3c", "conversion_id_2": "e3c65d75-d1fd-549c-9e63-4b303a01cd23", "is_flagged": false, "reason": "", "credit_estimate": 0.06 } ``` *** ## Webhook Sample Payload Music AI Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "album_cover_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/c287cca4-c03a-5074-b16a-b8da9d6a124c.jpg", "subtype": "music_ai" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` > Note: Each `conversion_id` corresponds to a different variation of the track. *** ## Payload and Request Formation # Music AI V2 Source: https://docs.musicgpt.com/api-documentation/conversions/musicaiv2 POST /v2/MusicAI Create music powered by AI using just a prompt, lyrics, or a defined music style. **Music AI v2** is our most advanced music generation model yet, faster generation, higher-quality audio, sharper prompt understanding, and more creative control than any version before it. ## Choose your model Studio-quality tracks in seconds, reliable, fast, and built for everyday creation. Everything in v6, now with real-time streaming so listeners hear the track as it's composed. Our best-sounding model yet, richer detail, more texture, state-of-the-art quality. The full power of v7 with real-time streaming and advanced creative controls. Our flagship. New here? Reach for **v7-pro** for the best quality, or drop to **v6** for the fastest, most economical generations. ### Model comparison | Model | Audio quality | Streaming | Best for | | - | - | - | - | | `v6` | Very good | - | Fast, dependable everyday tracks | | `v6-pro` | Very good | Real-time | Live, as-it-generates playback | | `v7` | Best-in-class | - | Highest-quality final renders | | `v7-pro` | Best-in-class | Real-time | Production apps that want everything | Pass your choice with the `model` parameter (`v6`, `v6-pro`, `v7`, or `v7-pro`). Streaming is available on the `pro` models for paid users. Per-model rates are listed on the [Pricing page](/api-documentation/index/pricing). If you provide a `voice_id` or set `vocal_only` to true, the request will always use the `v6` model, regardless of the value passed in the `model` parameter. ### Key features * Compose custom songs using your own lyrics and chosen music style * Generate complete tracks from a single prompt, including lyrics, instrumentation, and melody * Apply voice conversion using a custom voice model * Output full tracks, instrumental-only, or vocal-only versions * View the live streaming of the song as it generates (`pro` models) * Asynchronous webhook support for clean integration Every request returns **two distinct versions** of the track, so you always have a creative option to choose from. *** ## Endpoint ```http theme={null} POST /v2/MusicAI ``` This is the primary endpoint for initiating music generation. *** ## Sample Output Listen to a real sample output: Prompt: a song about greenery, nature and forest. Download Audio *** ## Try It Yourself Use the [MusicAI Endpoint Explorer](/api-documentation/endpoint/Musicaiv2) to test your own requests using prompts, lyrics, and more. > Each request returns **two distinct versions** of the track. *** ## Request Parameters | Parameter | Type | Required | Default | Description | | - | - | - | - | - | | `prompt` | String | Optional | - | A natural language prompt for music generation | | `title` | String | Optional | - | Title of the generated music | | `music_style` | String | Optional | - | Musical style or genre (e.g., Rock, Pop, Lo-fi) | | `lyrics` | String | Optional | "" | Custom lyrics to use in the song | | `make_instrumental` | Boolean | Optional | false | If true, generate instrumental-only audio | | `vocal_only` | Boolean | Optional | false | If true, generate vocals without instruments | | `voice_id` | String | Optional | "" | Apply voice model for vocal rendering | | `generate_album_cover` | Boolean | Optional | false | If `true`, generate an album cover for the generated audio | | `lyrics_timestamps` | Boolean | Optional | false | If true, generates lyric timestamps for the output track | | `model` | String | Optional | "v6" | Allowed values: `v6`, `v6-pro`, `v7`, `v7-pro` | | `webhook_url` | String | Optional | "" | URL to receive generated results via webhook | | `gender` | String | Optional | "" | Allowed values: male, female, neutral. | > **content-type:** application/json *** ## Generation Modes ### Custom Mode Provide your own `lyrics` and use `prompt` to describe the genre, vibe, instrumentation, and context. See the [Prompt Guideline](/api-documentation/utilities/prompt_guideline). ### Prompt Mode Supply only a `prompt` and let the system generate everything: lyrics, style, vocals, and more. > `make_instrumental`, `vocal_only`, and Music AI generation with custom `voice_id` are supported in both modes. *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests (non-instrumental): * 2 (webhook) x Music conversion details (one per version) * 2 (webhook) x Lyrics with timestamp data * 2 (webhook) x Streaming URL * 1 (webhook) x Album cover image #### Instrumental-only Requests: * 2 (webhook) x Music conversion details (one per version) * 2 (webhook) x Streaming URL * 1 (webhook) x Album cover image > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request (Python) ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v2/MusicAI" headers = { "Authorization": "", "Content-Type": "application/json" } payload = { "prompt": "Create a relaxing lo-fi song for studying", "lyrics": "It's a brand new day", "make_instrumental": False, "vocal_only": False, "title": "My Generated Track", "gender": "female", "generate_album_cover": True, "lyrics_timestamps": True, "model": "v7-pro", "webhook_url": "https://example.com/my-webhook" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` *** ## Sample Response ```json theme={null} { "success": true, "message": "Message published to queue", "task_id": "50c04348-7077-5ffd-a407-55f031db20ef", "eta": 154, "conversion_id_1": "5a2c6385-e2e1-5531-a530-aab3ff040a3c", "conversion_id_2": "e3c65d75-d1fd-549c-9e63-4b303a01cd23", "is_flagged": false, "reason": "", "credit_estimate": 0.06 } ``` *** ## Webhook Sample Payload Music AI Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "album_cover_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/c287cca4-c03a-5074-b16a-b8da9d6a124c.jpg", "subtype": "music_ai" } ``` Audio Streaming Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "subtype": "audio_streaming", "task_id": "80659560-54e7-5e59-a0a0-86320e92701b", "conversion_id": "10cfbe38-572a-5218-8981-5aa9a73aa8a5", "streaming_url": "https://cdn1.musicgpt.com/streams/22e4efb8-c8e7-42d7-a2f1-b094a9a92d24/index.m3u8" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Music AI", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` > Note: Each `conversion_id` corresponds to a different variation of the track. *** ## Payload and Request Formation # Remix Source: https://docs.musicgpt.com/api-documentation/conversions/remix POST /v1/Remix This endpoint allows users to remix an input audio file or URL using a descriptive prompt, optional lyrics, and a gender selection for vocal tone. Remix Audio Using Prompt and Optional Lyrics This endpoint allows users to remix an input audio file or URL using a descriptive prompt, optional lyrics, and a gender selection for vocal tone. *** ## Endpoint ```http theme={null} POST /v1/Remix ``` *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `title` | `String` | Optional | Title of the generated music | | `audio_file` | `File` | Optional | Upload the audio file directly. Required if `audio_url` is not provided. | | `audio_url` | `String` | Optional | URL to the audio file. | | `prompt` | `String` | βœ… Yes | Describes how the audio should be transformed. | | `lyrics` | `String` | Optional | Lyrics to guide remix or vocal generation. Max 5000 characters. | | `gender` | `String` | Optional | Vocal tone. One of: `male`, `female`, `neutral`. | | `generate_album_cover` | Boolean | Optional | If `true`, generate an album cover for the generated audio. Defaults to `false`. | | `lyrics_timestamps` | Boolean | Optional | If `true`, generates lyric timestamps for the output track. Defaults to `false`. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 4 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either `audio_file` or `audio_url` must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to a real output: Prompt: remix in classical slow vibe - audio input : Moana How Far We will Go. Download Audio *** ## Try it Yourself Use the [Remix Endpoint Explorer](/api-documentation/endpoint/remix) to test this endpoint live. *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests (non-instrumental): * 2 (webhooks) x Remix conversion details (one per version) * 2 (webhooks) x Lyrics with timestamp data * 1 Album Cover Image β€” sent only when `generate_album_cover` is `true` > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/Remix" \ -H "accept: application/json" \ -H "Authorization: " \ -F "audio_file=@/path/to/your/audio.mp3" \ -F "prompt=Make it sound like Lo-fi with chill beats" \ -F "lyrics=It's a brand new day" \ -F "gender=female" \ -F "webhook_url=https://example.com/my-webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/Remix" headers = {"Authorization": ""} data = { "prompt": "Make it sound like Lo-fi with chill beats", "lyrics": "It's a brand new day", "gender": "female", "generate_album_cover": True, "lyrics_timestamps": True, "title": "My Generated Track", "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url files = {} data["audio_url"] = "" response = requests.post(url, headers=headers, data=data, files=files) # 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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "message": "Remix request submitted successfully", "task_id": "2e70b1bc-0af7-45b2-bca5-5d951bd6a8fb", "conversion_id_1": "64a38c01-d5b9-4ffa-99d1-e38d957e7048", "conversion_id_2": "d12445e4-2605-4c4b-98a0-82efb36ad512", "is_flagged": false, "reason": "", "eta": 300, "status": "IN_QUEUE", "credit_estimate": 0.1, "error_message": "", "error_message_detail": "", "missing_input_fields": "", "predicted_user_intent": "" } ``` *** ## Webhook Sample Payload Remix Webhook ```json theme={null} { "success": true, "conversion_type": "Remix", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "subtype": "remix" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Remix", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Remix", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Missing required field `prompt`, or neither `audio_file` nor `audio_url` provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): An error occurred during processing or task queueing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Sing Over Instrumental Source: https://docs.musicgpt.com/api-documentation/conversions/sing_over_instrumental POST /v1/sing_over_instrumental This endpoint allows users to sing over an instrumental audio track using a text prompt and lyrics. It supports either a file upload or a URL to the input audio and generates a vocal overlay based on the provided lyrics and style. Generate a sung vocal performance over an instrumental audio track using a style prompt and lyrics. *** ## Endpoint ```http theme={null} POST /v1/sing_over_instrumental ``` This endpoint enables you to overlay vocals onto an instrumental audio using a textual description of the singing style and provided lyrics. Input can be either a file upload or a URL. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `title` | `String` | Optional | Title of the generated music | | `audio_file` | `UploadFile` | Optional | Upload the instrumental audio file. Required if `audio_url` is not provided. | | `audio_url` | `String` | Optional | URL to the audio file. | | `prompt` | `String` | Required | Text describing the desired singing style. Example: "Sing in soft jazz style" | | `lyrics` | `String` | Required | The lyrics to be sung over the instrumental. Max 5000 characters. | | `gender` | `String` | Optional | Voice style. Options: `male`, `female`, `neutral`. | | `generate_album_cover` | Boolean | Optional | If `true`, generate an album cover for the generated audio | | `lyrics_timestamps` | Boolean | Optional | If true, generates lyric timestamps for the output track | | `webhook_url` | `String` | Optional | Callback URL to receive processing results. | > **Max input audio length:** 4 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Output Listen to a real output: Prompt: sing over instrumental in classical slow vibe - audio input : Moana How Far We will Go. Download Audio *** ## Try it Yourself Use the [Sing Over Insturmental Endpoint Explorer](/api-documentation/endpoint/sing_over_instrumental) to test this endpoint live with your own inputs. *** ## Webhook Delivery Once the generation is complete, **webhooks** will be triggered to deliver the following: #### Standard Requests (non-instrumental): * 2 (webhooks) x Sing Over conversion details (one per version) * 2 (webhooks) x Lyrics with timestamp data * 1 Album Cover Image β€” sent only when `generate_album_cover` is `true` > Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc. *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/sing_over_instrumental" \ -H "accept: application/json" \ -H "Authorization: " \ -F "audio_url=" \ -F "prompt=Sing like Adele in a soulful tone" \ -F "lyrics=Never mind I'll find someone like you..." \ -F "gender=female" \ -F "webhook_url=https://yourdomain.com/webhook" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/sing_over_instrumental" headers = {"Authorization": ""} data = { "prompt": "Sing emotional vocals over a soft piano instrumental", "lyrics": "Never mind I'll find someone like you...", "gender": "female", "webhook_url": "https://yourdomain.com/webhook" } # Option 1: Use audio_url data["audio_url"] = "" response = requests.post(url, headers=headers, data=data) # Option 2: File upload # with open("audio.mp3", "rb") as f: # files = {"audio_file": f} # response = requests.post(url, headers=headers, data=data, files=files) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success": true, "message": "Sing Over Instrumental request submitted successfully", "task_id": "653c5108-c827-4568-9671-9259fd6b44cc", "conversion_id_1": "1d712957-00d9-493a-a6aa-8497ccaea9bc", "conversion_id_2": "7d6fa7a2-292c-4a95-8bda-df8ccce44bef", "is_flagged": false, "reason": "", "eta": 258, "status": "IN_QUEUE", "credit_estimate": 0.1, "error_message": "", "error_message_detail": "", "missing_input_fields": "", "predicted_user_intent": "" } ``` *** ## Webhook Sample Payload Sing Over Instrumental Webhook ```json theme={null} { "success": true, "conversion_type": "Sing Over Instrumental", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "conversion_path_wav": "https://cdn1.musicgpt.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav", "conversion_duration": 155.95, "is_flagged": false, "reason": "", "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]", "title": "Rhythm Take Control", "subtype": "remix" } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Sing Over Instrumental", "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg", "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36", "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` Lyrics Timestamp Webhook ```json theme={null} { "success": true, "conversion_type": "Sing Over Instrumental", "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c", "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2", "subtype": "lyrics_timestamped", "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Missing required fields like `prompt` or `lyrics`, or no audio input provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): Unexpected error during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** # Sound Generator Source: https://docs.musicgpt.com/api-documentation/conversions/soundgenerator POST /v1/sound_generator Creates an audio file based on a textual prompt. The generation process is asynchronous and returns a task ID for tracking.
Pro model Free all October

Sound Generator Pro

Our fastest, highest-quality sound model yet, now powering every request to /v1/sound\_generator. Free throughout October for up to 500 generations/day and 21/hour; after October, pricing is more than 3x lower than before.

\$0all of October
500generations / day
21generations / hour
3xcheaper after October
See the new pricing β†’ Open the playground

Free throughout October for paid plans.

Create custom sounds with AI using just a simple prompt. **Sound Generator** lets you synthesize high-quality sound effects and audio textures directly from text prompts. Perfect for developers, game designers, filmmakers, and creative technologists who need original sounds on demand. * Generate realistic or abstract sounds * Fine-tuned AI audio creation * Instant feedback or asynchronous delivery via webhook Sound Generator is designed for flexibility, speed, and professional-grade quality. *** ## What it supports | Feature | What it creates | Example prompt | | - | - | - | | **Sound FX** | A one-shot sound, action, ambience, or short audio scene. | Generate sound FX of a realistic car crash with tire skid, metal impact, and brief glass shatter; no music; 6 seconds. | | **Loops** | Repeatable audio designed to cycle seamlessly at a stated tempo. | Generate loop of tight kick and snare at 80 BPM in 4/4, four bars, with a clean loop point and no vocals. | | **Samples** | A single musical note, chord, hit, texture, or short isolated phrase. | Generate sample of a clean E major chord on acoustic guitar, one sustained hit with natural decay and no other instruments. | *** ## Special features Specify an exact tempo in your prompt (e.g. "at 90 BPM") and the output locks to it, so loops sync cleanly with an existing track. Everyday, real-world sounds like footsteps, cloth rustle, or object handling, ready to layer into film, video, and game audio. Set the exact duration, from **5 seconds to 2 minutes**, with the `audio_length` parameter. *** ## Endpoint ```http theme={null} POST /v1/sound_generator ``` Use this endpoint to generate sounds based on a text description. *** ## Sample Output Listen to an actual sample: Prompt: sound of bird chirping in a forest. Download Audio *** ## Try it Yourself Visit the [Sound Generator Endpoint Explorer](/api-documentation/endpoint/soundgenerator) to try live prompt-based sound creation. > πŸš€ Experiment with different descriptions β€” from realistic sounds (like "city street at night") to fantastical ones ("alien spacecraft landing")! *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `prompt` | String | Yes | A natural language description of the sound you want. Maximum 300 characters. | | `webhook_url` | String | Optional | Webhook URL to receive a callback with the audio result | | `audio_length` | Integer | Optional | Duration of the generated audio in seconds, from `5` to `120` | | `generate_album_cover` | Boolean | Optional | If `true`, generate an album cover for the generated audio | > **content-type:** application/x-www-form-urlencoded *** ## Sample Request ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/sound_generator" payload = { "prompt": "Generate a soothing ambient soundscape.", "generate_album_cover": "false", "webhook_url": "http://your-webhook-url.com/callback", "audio_length": "30" } headers = { "Authorization": "", "Content-Type": "application/x-www-form-urlencoded" } response = requests.post(url, data=payload, headers=headers) print(response.text) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"26c9aaf8-f292-4c66-992b-7f3c7dfe85fe", "conversion_id":"31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7", "eta":84, "credit_estimate":0.011, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response Once the sound is ready, your webhook will receive: * 1 Sound Generator webhook * 1 Album Cover webhook β€” sent only when `generate_album_cover` is `true` Sound Generator Webhook ```json theme={null} { "success": true, "conversion_type": "Sound Creator", "task_id": "26c9aaf8-f292-4c66-992b-7f3c7dfe85fe", "conversion_id": "31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/standard/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe.mp3", "conversion_path_wav": null, "conversion_duration": 30.0, "message": "Audio Generation Completed Successfully", "title": "Sound Creator", "conversion_paths": {"31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7": "https://cdn1.musicgpt.com/conversions/api/standard/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe.mp3"}, "conversion_paths_wav": {"31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7": null}, "conversion_durations": { "31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7": 30.0} } ``` Album Cover Webhook ```json theme={null} { "success": true, "conversion_type": "Sound Creator", "task_id": "26c9aaf8-f292-4c66-992b-7f3c7dfe85fe", "image_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe.jpg" ], "thumbnail_paths": [ "https://cdn1.musicgpt.com/img-gen-pipeline/api/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe_thumb.jpg" ], "image_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe.jpg", "thumbnail_path": "https://cdn1.musicgpt.com/img-gen-pipeline/api/26c9aaf8-f292-4c66-992b-7f3c7dfe85fe_thumb.jpg", "conversion_id_1": "31b6c4a2-e5e2-44ab-baf1-93ffa4c8a7b7", "album_cover_generator_output": true, "subtype": "album_cover_generation" } ``` > Note: If your webhook is set, you’ll get the sound automatically once ready. Otherwise, you can fetch it manually using the `conversion_id`. *** ## Payload and Request Formation # Text To Speech Source: https://docs.musicgpt.com/api-documentation/conversions/texttospeech POST /v1/TextToSpeech Synthesize speech from text with voice and gender customization, plus optional webhook callback. Give priority to the sample audio first, then to the voice ID, and lastly to gender. Convert any given text into realistic speech using your chosen voice and gender. **TextToSpeech** enables you to instantly bring written content to life. Perfect for: * Creating dynamic audio narrations or voiceovers * Choosing gender-specific voice stylings for different contexts * Using webhooks for real-time integration with your workflows *** ## Endpoint ```http theme={null} POST /v1/TextToSpeech ``` Use this endpoint to initiate a new text-to-speech audio generation. *** ## Sample Output Prompt: When I think of superheroes I think of super humans. I think of Superman, Wolverine and Wonder Woman. Usually they have a cape, or a mask to hide their face just in case. They have X-ray vision and super-human strength. Some can even breathe in outer space. They fly around a while, but always come back to keep our cities safe. They’re here to save humanity from itself. It’s a metaphor for how we look outside ourselves for help, and while the fantasies are fun, I choose to look for me and you. Download Audio *** ## Try it Yourself Visit the [TextToSpeech Endpoint Explorer](/api-documentation/endpoint/TextToSpeech) to try your own text samples. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `text` | String | Yes | The text content to convert to speech | | `voice_id` | String | Optional | Voice ID of the artist. Visit [Get Voices by Name](/api-documentation/endpoint/searchVoices) to get voice\_id. | | `sample_audio_url` | String | Optional | URL of Voice you want. | | `gender` | String | Yes | Gender of the voice ("male", "female") | | `webhook_url` | String | No | URL to receive a callback with generated audio | > **content-type:** application/json *** ## Sample Request ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/TextToSpeech" headers = { "Authorization": "", "Content-Type": "application/json" } payload = { "text": "Welcome to MusicGPT! This is a sample text-to-speech generation.", "sample_audio_url": "", "voice_id": "e1cb7380-e3db-433a-b186-a996d7545986", "gender": "female", "webhook_url": "https://example.com/my-webhook" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"0a65cbb6-2ab8-4949-9ee0-0e8c138ac2cf", "conversion_id":"6542baa6-d61f-4d90-b832-ed929d9c0996", "eta":17, "credit_estimate":0.68, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response Once audio is ready, your webhook will receive: ```json theme={null} { "success": true, "conversion_type": "Text To Speech", "task_id": "037a9a09-3fc6-4a90-8748-d3406ff712eb", "conversion_id": "f1970224-ab06-4aa6-a832-0f3fd23212b7", "conversion_path": "https://cdn1.musicgpt.com/conversions/api/tts/195e5815-b871-4ea0-86a2-7f5eb1c696d2/195e5815-b871-4ea0-86a2-7f5eb1c696d2.mp3", "message": "Conversion Completed", "title": "Text To Speech", "conversion_cost": "0.68", "conversion_duration": 27.78 } ``` *** ## Error Codes * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Not enough credits to process the request. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): Invalid or missing fields. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): Server-side failure during processing. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # Voice Changer Source: https://docs.musicgpt.com/api-documentation/conversions/voicechanger POST /v1/VoiceChanger Convert the voice from an audio file or URL to a different voice. Convert the voice from an audio file or URL to a different voice using AI voice models. The **VoiceChanger** endpoint provides real-time voice transformation by modifying the pitch, removing background noise, and converting the voice using a selected model. Ideal for creative content, dubbing, or personalized audio experiences. *** ## Endpoint ```http theme={null} POST /v1/VoiceChanger ``` This is the primary endpoint for initiating voice conversion tasks. *** ## Sample Output Listen to a real sample output: Output File: Download Audio *** ## Try it Yourself Visit the [VoiceChanger Endpoint Explorer](/api-documentation/endpoint/voicetovoice) to test it live. Upload a sample, pick a voice, and experience real-time voice transformation. *** ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `audio_url` | `String` | Optional | URL of the audio file. Either `audio_url` or `audio_file` must be provided. | | `audio_file` | `File` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. | | `voice_id` | `String` | βœ… Yes | Voice model to convert the audio into. | | `remove_background` | `Integer` | Optional | Set to `1` to remove background noise. Default is `0`. | | `pitch` | `Integer` | Optional | Adjust pitch between -12 and 12 semitones. Default is `0`. | | `webhook_url` | `String` | Optional | Callback URL for async response. | > **Max input audio length:** 8 minutes. See [Audio Length Limits](/api-documentation/utilities/ratelimits#audio-length-limits). > **Note:** Either audio\_file or audio\_url must be provided. > **content-type:** multipart/form-data *** ## Sample Request ### cURL ```bash theme={null} curl -X POST "https://api.musicgpt.com/api/public/v1/VoiceChanger" \ -H "Authorization: " \ -F "voice_id=e0bb585f-b798-4bac-ac4e-de7fff38f9d75" \ -F "remove_background=1" \ -F "pitch=0" \ -F "webhook_url=https://example.com/my-webhook" \ -F "audio_url=" ``` ### Python ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/VoiceChanger" headers = { "Authorization": "" } data = { "voice_id": "e0bb585f-b798-4bac-ac4e-de7fff38f9d75", "remove_background": 1, "pitch": 0, "webhook_url": "https://example.com/my-webhook" } # Option 1: audio_url data["audio_url"] = "" # This endpoint expects multipart/form-data, so send the fields as form parts response = requests.post( url, headers=headers, files={k: (None, str(v)) for k, v in data.items()} ) # 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()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id": "fdcca59e-9788-43fc-9ee6-e9983064c432", "conversion_id":"3b8dd3e8-104a-4a2f-86ba-3ed722f5190a", "eta":16, "credit_estimate":1.07, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response ```json theme={null} { "success": true, "conversion_type": "Voice Conversion", "task_id": "fdcca59e-9788-43fc-9ee6-e9983064c432", "conversion_id": "67092f68-045d-4e3c-8006-532f144dd610", "conversion_path": "https://cdn1.musicgpt.com/projects/standard/ffa2da3a-af79-4cbd-9cf6-ea178c9b2f90.mp3", "conversion_cost": "0.78", "conversion_duration": 272.44, "title": "Voice Conversion", "message": "Conversion Completed" } ``` *** ## Common Errors * **402 Payment Required** (`INSUFFICIENT_CREDITS`): Your credit balance is insufficient. * **422 Unprocessable Entity** (`UNPROCESSABLE_CONTENT`): No `audio_url` or `audio_file` provided. * **500 Internal Server Error** (`INTERNAL_SERVER_ERROR`): Something went wrong on our end. See [Handling Errors](/api-documentation/utilities/error) for the error response format and all error codes. *** ## Payload and Request Formation # MUSIC AI Source: https://docs.musicgpt.com/api-documentation/endpoint/MusicAI POST /v1/MusicAI Create music powered by AI using just a prompt, lyrics, or a defined music style. # MUSIC AI V2 Source: https://docs.musicgpt.com/api-documentation/endpoint/Musicaiv2 POST /v2/MusicAI Create music powered by AI using just a prompt, lyrics, or a defined music style. # Text To Speech Source: https://docs.musicgpt.com/api-documentation/endpoint/TextToSpeech POST /v1/TextToSpeech Synthesize speech from text with voice and gender customization, plus optional webhook callback. Give priority to the sample audio first, then to the voice ID, and lastly to gender. # Audio Cutter Source: https://docs.musicgpt.com/api-documentation/endpoint/audio_cutter POST /v1/audio_cutter Trims an audio file using the specified start and end times. # Audio Mastering Source: https://docs.musicgpt.com/api-documentation/endpoint/audio_mastering POST /v1/audio_mastering Processes an input audio file to match the mastering characteristics of a reference track. # Audio Speed Changer Source: https://docs.musicgpt.com/api-documentation/endpoint/audio_speed_changer POST /v1/audio_speed_changer Processes an audio file to change its playback speed based on a speed factor. # Audio To MIDI Source: https://docs.musicgpt.com/api-documentation/endpoint/audio_to_midi POST /v1/audio_to_midi Processes an audio file and converts it into a MIDI file. Optionally generates a sonified .wav and/or a CSV of note events. This request is handled asynchronously. # Audio Transcribe Source: https://docs.musicgpt.com/api-documentation/endpoint/audiotranscribe POST /v1/audio_transcribe Processes an audio file to generate a transcription of the spoken content with support for language detection, translation, and multiple output formats. # Cover Source: https://docs.musicgpt.com/api-documentation/endpoint/cover POST /v1/Cover Convert an audio file or URL into a cover song using a different voice. # DeEcho Source: https://docs.musicgpt.com/api-documentation/endpoint/deecho POST /v1/deecho Initiate an echo removal task using either an audio URL or file upload with optional webhook callback. # DeNoise Source: https://docs.musicgpt.com/api-documentation/endpoint/denoise POST /v1/denoise Initiate a noise removal task using either an audio URL or file upload with optional webhook callback. # DeReverb Source: https://docs.musicgpt.com/api-documentation/endpoint/dereverb POST /v1/dereverb Initiate a reverberation removal task using either an audio URL or file upload with optional webhook callback. # Extend Source: https://docs.musicgpt.com/api-documentation/endpoint/extend POST /v1/extend This endpoint allows users to extend an existing audio file or stream by appending new audio content after a specific timestamp. The new audio is generated using a prompt (e.g., describing the desired sound) and optional lyrics. # Extract Key BPM Source: https://docs.musicgpt.com/api-documentation/endpoint/extract_key_bpm POST /v1/extract_key_bpm Processes an audio file to extract key changes, dominant key, and BPM (Beats Per Minute). # Extraction Source: https://docs.musicgpt.com/api-documentation/endpoint/extraction POST /v2/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. # File Conversion Source: https://docs.musicgpt.com/api-documentation/endpoint/fileconvert POST /v1/file_convert Initiate a file conversion task using either an audio URL or file upload with optional format parameters and webhook callback. # Get All Voices Source: https://docs.musicgpt.com/api-documentation/endpoint/getAllVoices GET /v1/getAllVoices Fetch all available voices with their IDs. # Get Conversion Details By ID Source: https://docs.musicgpt.com/api-documentation/endpoint/getById GET /v1/byId Retrieve details of a conversion using `task_id` or `conversion_id`. # Image to Song Source: https://docs.musicgpt.com/api-documentation/endpoint/imagetosong POST /v1/image_to_song Generate a song from an image by analyzing it and creating music based on visual content. The process can optionally include custom lyrics, voice conversion, and various musical parameters. # Inpaint Source: https://docs.musicgpt.com/api-documentation/endpoint/inpaint POST /v1/inpaint This endpoint allows users to replace a specific time segment of an audio clip using a textual prompt and optional lyrics. The inpainting operation blends new audio content into the selected range, guided by user-defined style and voice preferences. To use the inpaint feature, upload a song and specify the lyrics you want to replace in the field **'lyrics_section_to_replace'**. For best results, also provide the complete song lyrics in the **lyrics**. # Lyrics Generator Source: https://docs.musicgpt.com/api-documentation/endpoint/lyrics_generator GET /v1/prompt_to_lyrics This endpoint takes a natural language prompt (e.g., a theme, vibe, or idea) and generates original lyrics based on it. If the prompt has been used before, a variation may be returned. It also estimates the credit cost of generation. # Remix Source: https://docs.musicgpt.com/api-documentation/endpoint/remix POST /v1/Remix This endpoint allows users to remix an input audio file or URL using a descriptive prompt, optional lyrics, and a gender selection for vocal tone. # Get Voices by Name Source: https://docs.musicgpt.com/api-documentation/endpoint/searchVoices GET /v1/searchVoices Search for voices to get their voice ID by their names using a query string. # Sing Over Instrumental Source: https://docs.musicgpt.com/api-documentation/endpoint/sing_over_instrumental POST /v1/sing_over_instrumental This endpoint allows users to sing over an instrumental audio track using a text prompt and lyrics. It supports either a file upload or a URL to the input audio and generates a vocal overlay based on the provided lyrics and style. # Sound Generator Source: https://docs.musicgpt.com/api-documentation/endpoint/soundgenerator POST /v1/sound_generator Creates an audio file based on a textual prompt. The generation process is asynchronous and returns a task ID for tracking. # Voice Changer Source: https://docs.musicgpt.com/api-documentation/endpoint/voicetovoice POST /v1/VoiceChanger Convert the voice from an audio file or URL to a different voice. # FAQs Source: https://docs.musicgpt.com/api-documentation/index/FAQs

To get the best results, follow these rules:

  • Keep prompts descriptive and simple
  • Prompt limit: 1000 characters
  • Lyrics limit: 5000 characters

You can describe song sections like this:

      \[Intro – soft piano and light synths]
      \[Chorus – repeat with more intensity]
      \[Bridge – add soft strings or a subtle beat drop]

Note: Do not include any artist names.
  1. Go to the API Dashboard
  2. Open Plans
  3. Click on Free

Your plan will be downgraded immediately.

Use the following endpoints:

  • [GET /endpoint/searchVoices](/api-documentation/endpoint/searchVoices)
  • [GET /endpoint/getAllVoices](/api-documentation/endpoint/getAllVoices)

The response includes the required voice\_id.

Plans do not include credits.

However, the cost per API call is much lower in higher-tier plans.

Example (Music AI):

  • Pro Plan: \$0.035 per song
  • Plus Plan: \$0.05 per song
  • Pay as You Go: \$0.10 per song

If you are on the Pro plan, you first pay a \$69 base charge and top up credits. Credits are then deducted at \$0.035 per song, whereas on Pay as You Go, each song deducts \$0.10 per song.

WAV files are currently sent only for the following endpoints:

  • Music AI
  • Remix
  • Extend
  • Inpaint
  • Sing Over Instrumental

If you need help, please email us at [api@musicgpt.com](mailto:api@musicgpt.com) with a detailed description of your issue. If applicable, include relevant information such as your task\_id, API request, or any error messages to help us investigate more quickly.

Before you send anything, redact your credentials. Remove the Authorization header, API Keys, and any other sensitive data from requests, responses, and logs. Support never needs your API Key to investigate an issue.

Our team typically responds within 24 hours, and often much sooner. We're committed to providing fast, reliable, and high-quality support to help you get back on track.

# Authentication Source: https://docs.musicgpt.com/api-documentation/index/authentication ## Base URL API requests should be sent to: ``` https://api.musicgpt.com/api/public ``` ## Authentication All endpoints require an **API Key**. Include it in the `Authorization` header like this: ```bash theme={null} Authorization: YOUR_API_KEY ``` πŸ‘‰ [**Get your API Key here**](https://musicgpt.com/api) # Changelog Source: https://docs.musicgpt.com/api-documentation/index/changelog **Sound Generator** will be **free for the month of October**, with up to **500 generations/day, 21/hour**. It costs **more than 3x less**: from **\$0.012/generation** on the Pro plan (was \$0.037). See the [Pricing Page](/api-documentation/index/pricing).
**Remix, Extend, Inpaint, and Sing Over Instrumental** support audio lengths of up to **4 minutes**, while **all other features** support audio lengths of up to **8 minutes**.
Every conversion webhook now includes a `title` field. Updated **pricing structure** and **rate limits**. **Pay-As-You-Go** introduced. Visit [Pricing Page](/api-documentation/index/pricing).
**v2/MusicAI/stream** and **v2/MusicAI/batch** are deprecated.
Added [Prompt Guideline](/api-documentation/utilities/prompt_guideline).
Updated **prompt character limit to 1000** and **lyrics character limit to 5000 for Music AI and Remix.** **Model Selection** added to Audio Generation - choose from `v6`, `v6-pro`, `v7`, or `v7-pro` with the `model` parameter. See [Music AI V2](/api-documentation/conversions/musicaiv2).
**Streaming** is now available for **all paid users** on `v6-pro` and `v7-pro`.
Deprecated **Music AI V1**, please migrate to [Music AI V2](/api-documentation/conversions/musicaiv2).
Starting **August 1**, monthly plan pricing will be updated. **Extraction** endpoint updated. Added `eco_mode` to support faster parallel extraction.
Added **title** field to the Audio Generations feature.
Cover images are now **optional** in Audio Generation, enable it to receive a cover image along with the audio.
Added a **Streaming URL** webhook. Music AI V2 now provides 7 webhooks. Retention time: **MP3 files are stored for 90 days**, while **WAV files are stored for 7 days**.
**WAV files** will be sent in webhooks starting March 24, 2026.
Parameter to control the **number of song** outputs in Inpaint and Extend.
**Pricing** for Inpaint, Extend and Custom Voice Music Generator updated.
**Image to Song** feature introduced.
**Lyrics\_section\_to\_replace** added on extend and inpaint where people can specify lyrics they want to add or replace.
**Song length control** feature added in Music AI.
**Streaming available** for enterprise users. Go to Music AI v2.
**Single-Song generation** is now available for enterprise users. Go to Music AI Single Song.
**SDK and Tools** included in documentation.
Remix, Inpaint, Extend, and Sing Over Instrumental upgraded for **higher accuracy**.
Improved MusicAI output **quality**.
**Cover image** is now sent with Remix, Inpaint, Extend, and Sing Over Instrumental.
**No WAV** file will be sent in webhooks starting **February 9**. # Create an API Account Source: https://docs.musicgpt.com/api-documentation/index/createapiaccount Before you can make your first request, you need a Musicgpt API Account. 1. Head to [musicgpt.com/api](https://musicgpt.com/api) and click on **Get started** or select one of the available API Packages: 2. Enter your payment information. 3. πŸŽ‰ Congratulations! You now have a Musicgpt API Account and are ready to start making requests. 4. Checkout [API Dashboard](https://musicgpt.com/api-dashboard) - get your API Keys and start generating. # Introduction Source: https://docs.musicgpt.com/api-documentation/index/introduction MusicGPT Public API let's you turn any idea into production-ready audio with the world's most advanced AI models, through one simple API.
Live now New Β· Pro model

Sound Generator Pro is here

Studio-grade sound FX, loops, and samples from a single prompt. Our fastest, highest-quality sound model yet.

Sound FX Loops at any BPM Instrument samples Foley

Free for the whole month of October

Generate as many sounds as you need, then pay more than 3x less when the free period ends.

\$0all of October
500generations / day
21generations / hour
3xcheaper after October
## MusicGPT Public API Documentation Welcome to **MusicGPT**! Your **all-in-one AI-powered** music and audio platform. Our API lets you generate, remix, enhance, convert, and manipulate audio effortlessly, turning creative ideas into production-ready music. We offer: Whether you're building AI music applications, creating content at scale, or developing professional audio workflows, Music AI V2 delivers enterprise-grade music generation and advanced audio capabilities through a simple API. Generate songs, transform voices, edit audio, extract stems, and more with ease. *** ## One endpoint, four models πŸŽ›οΈ **Music AI V2** introduces **model-based versioning**: every generation request can name the model it runs on, so you choose the exact balance of speed, quality, and cost and upgrade on your own schedule as new models ship. Studio-quality tracks in seconds, reliable, fast, and the most economical choice for everyday creation. Everything in v6, plus real-time streaming so listeners hear the track as it's composed. Our best-sounding model yet, richer detail, more texture, state-of-the-art quality. The full power of v7 with real-time streaming and advanced creative controls. Our flagship. Pick a model by passing the `model` parameter on [Music AI v2](/api-documentation/conversions/musicaiv2): ```json theme={null} { "prompt": "a song about greenery, nature and forest", "model": "v7-pro" } ``` New here? Reach for **v7-pro** for the best quality, or drop to **v6** for the fastest, most economical generations. Streaming is available on the `pro` models for all paid users. *** ## Features Highlights MusicGPT is a comprehensive AI audio platform offering a wide range of features including: * **Music Generation** (Music AI): Turn text prompts into full-length songs. * **Remixing and Editing Tools**: Cut, master, change pitch/speed, remix, inpaint and more. * **Text-to-Speech (TTS)**: Convert text to expressive voice using custom voice profiles. * **Voice Changing**: Convert any voice into a new one, ideal for character work, privacy, or creativity. * **Cover Song Generation**: Recreate any song with a new voice or style. * **Vocal, Instrumental and Stems Extraction**: Isolate or remove vocals, instruments, or stems. * **Audio Cleaning**: De-noise, de-echo, and de-reverb your recordings. * **Key/BPM Detection**: Instantly extract musical key and tempo. * **Transcription**: Get accurate text from speech. * **File Format Conversion**: Seamlessly convert between audio formats. *** ## Why Developers Love MusicGPT * **Model selection** - pick the exact speed/quality/cost trade-off per request * **Powerful & easy-to-use API** * **Webhook support for async jobs** * **Flexible pricing with free tier and yearly rate lock** * **Fast processing & global CDN delivery** * **Real-time status monitoring** * **Secure & scalable infrastructure** *** ## Real-World Use Cases * Content creators auto-dubbing podcasts or YouTube videos * Music producers generating and remixing audio at scale * Developers building music-based apps or smart audio tools * Researchers experimenting with generative audio AI *** ## Helpful Links πŸ”— * [API Dashboard](https://musicgpt.com/api-dashboard) * [MusicGPT](https://musicgpt.com) * [Music AI v2](/api-documentation/conversions/musicaiv2) * [Pricing & yearly plans](/api-documentation/index/pricing) *** Now let's dive into how you can get started in minutes πŸ‘‡ # Keys to the Castle Source: https://docs.musicgpt.com/api-documentation/index/keystocastle To make requests to the Musicgpt API, you need to create an API Key πŸ”‘ Head to your [API Dashboard](https://musicgpt.com/api-dashboard) and click on API Keys. If you don't have a key, click on Create key, give it a name, and click Create API Key. Click on the Eye Symbol πŸ‘€ next to your key to reveal it. πŸŽ‰ Congratulations! You’ve gained access. # Pricing Plans Source: https://docs.musicgpt.com/api-documentation/index/pricing Flexible plans that lower your per-request rates, now with yearly billing that locks in current pricing. Discover our flexible pricing options designed to scale with your creativity. Start free and upgrade anytime for more features, faster processing, and priority support. All paid plans include **commercial use**, **high-speed processing**, **studio-quality audio**, and **dedicated support**. **Plans don't give you credits**, they lower the cost of each API call. You are still billed per request based on your plan's rate. **Pay as You Go** is the exception: instead of lowering a rate, you add credits up front and each request draws them down.

Get upto 10 free song generations

1. Activate your API account. 2. Get your API key. 3. Start creating for free.

## Plans The pricing structure for the **AI Music Generator** has been updated effective **August 1**. | Feature | Model | Pro Plan | Plus Plan | Pay as You Go | | - | :-: | -: | -: | -: | | [AI Music Generator](/api-documentation/conversions/musicaiv2)
Generate AI music from prompt | `v7-pro` | \$0.06 /song | Not available | Not available | | | `v7` | \$0.05 /song | Not available | Not available | | | `v6-pro` | \$0.045 /song | \$0.06 /song | Not available | | | `v6` | \$0.035 /song | \$0.05 /song | \$0.10 /song | | [Custom Voice Music Generator](/api-documentation/conversions/musicaiv2)
Generate AI song with voice you like | `v6` | \$0.052 /song | \$0.075 /song | \$0.15 /song | | [Remix](/api-documentation/conversions/remix)
Remix audio into a new music style | `v6` | \$0.05 /song | \$0.07 /song | \$0.14 /song | | [Inpaint](/api-documentation/conversions/inpaint)
Replace Audio Section | `v6` | \$0.06 /song | \$0.10 /song | \$0.20 /song | | [Extend](/api-documentation/conversions/extend)
Extend the input audio | `v6` | \$0.06 /song | \$0.10 /song | \$0.20 /song | | [Sing Over Instrumental](/api-documentation/conversions/sing_over_instrumental)
Blend Lyrics with Instrumental | `v6` | \$0.05 /song | \$0.07 /song | \$0.14 /song | AI Music, Custom Voice Music, Remix, Inpaint, Extend, and Sing Over Instrumental generate 2 output versions by default. All features use 60-second increments (except Text-to-Speech, which uses 100 words). ## Voice & Audio Features [Sound Generator](/api-documentation/conversions/soundgenerator) is **free throughout October 2026**, up to **500 generations/day** and **21 generations/hour**. The rates below apply after the free period ends. | Feature | Pro Plan | Plus Plan | Pay as You Go | | - | - | - | -: | | [Text to Speech](/api-documentation/conversions/texttospeech)
Convert text into speech | \$0.026/100 words | \$0.035/100 words | \$0.07/100 words | | [Sound Generator](/api-documentation/conversions/soundgenerator)
Generate sounds from prompt | \$0.012 /generation | \$0.014 /generation | \$0.028 /generation | | [Lyrics Generator](/api-documentation/conversions/lyrics_generator)
Generate Lyrics from prompt | \$0.005 /generation | \$0.005 /generation | \$0.01 /generation | | [Voice Changer](/api-documentation/conversions/voicechanger)
Transform voice in audio | \$0.016 + \$0.0022/min | \$0.022 + \$0.003/min | \$0.044 + \$0.006/min | | [Cover Song](/api-documentation/conversions/cover)
Create AI-generated cover songs | \$0.0235 + \$0.0037/min | \$0.0315 + \$0.005/min | \$0.063 + \$0.01/min | ## Stem Splitter Features Pricing | Feature | Pro Plan | Plus Plan | Pay as You Go | | - | - | - | -: | | [Vocal Extraction](/api-documentation/conversions/extraction)
Isolate vocals from track | \$0.0115 + \$0.0022/min | \$0.0155 + \$0.003/min | \$0.031 + \$0.006/min | | [Gender-Based Vocal Extraction](/api-documentation/conversions/extraction)
Split male and female vocals | \$0.0186 + \$0.003/min | \$0.0248 + \$0.0045/min | \$0.0496 + \$0.009/min | | [Lead/Back Vocals Separation](/api-documentation/conversions/extraction)
Split lead and backing vocals | \$0.0242 + \$0.0037/min | \$0.0322 + \$0.005/min | \$0.0644 + \$0.01/min | | [Instrumental Extraction](/api-documentation/conversions/extraction)
Extract instrumental parts | \$0.0576 + \$0.0089/min | \$0.0768 + \$0.012/min | \$0.1536 + \$0.024/min | | [Guitar Type Stems](/api-documentation/conversions/extraction)
Split acoustic/electric guitars | \$0.0576 + \$0.1289/min | \$0.0768 + \$0.1319/min | \$0.1536 + \$0.2638/min | | [Guitar Part Stems](/api-documentation/conversions/extraction)
Separate rhythm & solo guitar | \$0.0576 + \$0.1289/min | \$0.0768 + \$0.1319/min | \$0.1536 + \$0.2638/min | | [Strings Stems](/api-documentation/conversions/extraction)
Separate string instruments | \$0.0576 + \$0.0989/min | \$0.0768 + \$0.1019/min | \$0.1536 + \$0.2038/min | | [Keys Extraction](/api-documentation/conversions/extraction)
Extract piano & keys | \$0.067 + \$0.0104/min | \$0.089 + \$0.0134/min | \$0.178 + \$0.0268/min | | [Winds Splitter](/api-documentation/conversions/extraction)
Split wind instruments | \$0.0727 + \$0.0119/min | \$0.097 + \$0.0149/min | \$0.194 + \$0.0298/min | | [Band Parts Splitter](/api-documentation/conversions/extraction)
Extract drums, bass, piano, guitar | \$0.1078 + \$0.0179/min | \$0.1438 + \$0.0238/min | \$0.2876 + \$0.0476/min | | [Premium Bass/Drums Split](/api-documentation/conversions/extraction)
High-accuracy drums/bass isolation | \$0.2455 + \$0.0372/min | \$0.3273 + \$0.0521/min | \$0.6546 + \$0.1042/min | | [Drum Stems Separation](/api-documentation/conversions/extraction)
Separate Drum Stems | \$0.1078 + \$0.0179/min | \$0.1438 + \$0.0238/min | \$0.2876 + \$0.0476/min | > **Example** : For Vocal Extraction Pro plan, a 3-minute song costs 0.0115+(0.0022Γ—3). ## Audio Enhancement Features Pricing | Feature | Pro Plan | Plus Plan | Pay as You Go | | - | - | - | -: | | [Voice Cleaner](/api-documentation/conversions/denoise)
Remove background noise | \$0.0223 + \$0.0037/min | \$0.0298 + \$0.0045/min | \$0.0596 + \$0.009/min | | [DeEcho](/api-documentation/conversions/deecho)
Remove echo | \$0.0171 + \$0.003/min | \$0.0228 + \$0.0037/min | \$0.0456 + \$0.0074/min | | [DeReverb](/api-documentation/conversions/dereverb)
Remove reverb | \$0.0145 + \$0.0022/min | \$0.0193 + \$0.003/min | \$0.0386 + \$0.006/min | | [Audio Cutter](/api-documentation/conversions/audiocutter)
Trim specific parts of audio | \$0.003 + \$0.003/min | \$0.004 + \$0.004/min | \$0.008 + \$0.008/min | | [Speed Changer](/api-documentation/conversions/audiospeedchanger)
Adjust audio speed | \$0.003 + \$0.003/min | \$0.004 + \$0.004/min | \$0.008 + \$0.008/min | | [Audio Mastering](/api-documentation/conversions/audiomastering)
Master audio based on reference track | \$0.003 + \$0.003/min | \$0.004 + \$0.004/min | \$0.008 + \$0.008/min | | [File Converter](/api-documentation/conversions/fileconvert)
Convert audio formats | \$0.002 + \$0.0008/min | \$0.003 + \$0.0011/min | \$0.006 + \$0.0022/min | ## Audio Analysis Features Pricing | Feature | Pro Plan | Plus Plan | Pay as You Go | | - | - | - | -: | | [Key & BPM Detector](/api-documentation/conversions/extractkeybpm)
Detect BPM and musical key | \$0.00186 + \$0.0002/min | \$0.00248 + \$0.0003/min | \$0.00496 + \$0.0006/min | | [Audio Transcription](/api-documentation/conversions/audiotranscription)
Convert speech to text & translate | \$0.0223 + \$0.0037/min | \$0.0298 + \$0.0045/min | \$0.0596 + \$0.009/min | | [Audio to MIDI](/api-documentation/conversions/audiotomidi)
Generate MIDI from audio | \$0.005 + \$0.0037/min | \$0.007 + \$0.005/min | \$0.014 + \$0.01/min | ### Pricing Summary * **Base Cost**: One-time charge per request * **+/min**: Additional cost per minute (60s increments) * **Text-to-Speech**: Only feature using word count (per 100 words) * **Multiple Outputs**: AI Music, Custom Voice Music & Remix deliver 2 versions and its cost is based on per each song. > For custom plans, contact us at [api@musicgpt.com](mailto:api@musicgpt.com). ### API Usage Limits Visit the [Rate Limits](/api-documentation/utilities/ratelimits) page to learn about API usage limits. *** # SDK and Tools Source: https://docs.musicgpt.com/api-documentation/index/sdk We provide tools like our SDK and n8n integration to make using the API easier for developers. | Tools | Access | | - | - | | Zapier | [Zapier](https://zapier.com/apps/musicgpt/integrations) | | Packages | Access | | - | - | | Javascript(Node) | [npm](https://www.npmjs.com/package/musicgpt) | | Pypi | [pip](https://pypi.org/project/musicgpt/) | # Status Check Source: https://docs.musicgpt.com/api-documentation/index/statuscheck After performing a conversion via one of our API endpoints, you may want to check the progress or retrieve the final result. You can do this easily by calling our [**Get Conversion by ID**](/api-documentation/endpoint/getById) endpoint. *** ### Example Request Use the following code to check the status of any conversion using its `task_id`: ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v1/byId" querystring = { "conversionType": "MUSIC_AI", "task_id": "12345678-abcd-1234-efgh-567890abcdef" } headers = { "Authorization": "" } response = requests.request("GET", url, headers=headers, params=querystring) print(response.text) ``` > Select one among the following values for conversionType:

> MUSIC\_AI, TEXT\_TO\_SPEECH, VOICE\_CONVERSION,
> COVER, EXTRACTION, DENOISING, DEECHO, DEREVERB,
> SOUND\_GENERATOR, AUDIO\_TRANSCRIPTION, AUDIO\_SPEED\_CHANGER,
> AUDIO\_MASTERING, AUDIO\_CUTTER, REMIX, FILE\_CONVERT,
> KEY\_BPM\_EXTRACTION, AUDIO\_TO\_MIDI, EXTEND, INPAINT,
> SING\_OVER\_INSTRUMENTAL, LYRICS\_GENERATOR, STEMS\_SEPARATION, VOCAL\_EXTRACTION *** ### Example Response ```json theme={null} { "success": true, "conversion": { "task_id": "12345678-abcd-1234-efgh-567890abcdef", "conversion_id": "87654321-dcba-4321-hgfe-098765fedcba", "status": "COMPLETED", "status_msg": "Conversion successful", "audio_url": "", "conversion_cost": 1.25, "title": "Generated Song", "lyrics": "[Verse 1]...", "music_style": "Pop", "createdAt": "2025-01-01T12:00:00Z", "updatedAt": "2025-01-01T12:05:00Z" } } ``` You’ll receive details including: * `status`: Whether the conversion is **IN\_QUEUE**, **ERROR**, **COMPLETED**, or **FAILED**. * `status_msg`: A message describing the state. * `audio_url`: A direct link to your generated audio file if the status is completed. * Additional metadata such as title, lyrics, style, timestamps, and cost. *** ### Where to Start 1. First, perform a conversion via the [Conversion Endpoints](/api-documentation/conversions/musicai). 2. Save the `task_id` you receive in the response. 3. Use the **Get By ID** endpoint to check the progress. *** ### Still Unsure? No worries β€” head over to the [**Get Conversion by ID**](/api-documentation/endpoint/getById) endpoint and try it for yourself with your own `task_id`. It's the easiest way to confirm conversion status and get direct download access to your audio output! # Webhook Integration Source: https://docs.musicgpt.com/api-documentation/index/webhook When working with asynchronous processes like music generation, voice cloning, or instrumental extraction, waiting for a task to complete can slow down your workflow. That’s where **webhooks** come in handy. Webhooks allow Musicgpt to notify your application the moment a task is completed. You’ll get all the necessary data including the audio URL without needing to constantly poll our API. *** ### How It Works 1. **Set the `webhook_url`** when submitting your conversion request. 2. Musicgpt will **send a POST request** to that URL when the task is completed. 3. Your server can then parse the response and proceed with post-processing or user notifications. *** ### Sample Payload Here's what a typical webhook payload looks like: ```json theme={null} { "task_id": "12345678-abcd-1234-efgh-567890abcdef", "status": "COMPLETED", "status_msg": "Conversion successful", "conversion_type": "MUSIC_AI", "audio_url": "https://cdn1.musicgpt.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3", "title": "Generated Song", "conversion_cost": 1.25, "createdAt": "2025-01-01T12:00:00Z", "updatedAt": "2025-01-01T12:05:00Z" } ``` > πŸ”— Set the `webhook_url` to an endpoint on your server β€” this is where Musicgpt will notify you once the generation is done. *** ### Preliminary Response When you initiate a conversion request, Musicgpt will immediately respond with a **preliminary response** that includes: * `success`: whether the task was successfully initiated * `task_id`: a unique ID you can use to track the conversion Example: ```json theme={null} { "success": true, "task_id": "12345678-abcd-1234-efgh-567890abcdef" } ``` This response confirms that the request was accepted. However, the **final result** (like the downloadable file) will be sent **later** to your webhook URL. *** ### Can’t Use a Webhook? No problem β€” if you’re running code on a client device or you don’t have a public server, you can always check the conversion status manually using our helper endpoint: πŸ‘‰ [**Get Conversion by ID**](/api-documentation/endpoint/getById) *** ### Why Use Webhooks? * No need for polling or delays * Works in the background * Instantly delivers results * Ideal for automations and server workflows Set it once, and let Musicgpt notify you when the magic happens. 🎢 # The First Time Source: https://docs.musicgpt.com/api-documentation/index/yourfirstrequest Welcome to your **first experience** with the Musicgpt API, where creativity meets technology. Browse the wide range of features available for you through our API. *** ## Integrate in 5 minutes with 5 steps:
"A single API offering 20+ powerful features"
1. [Activate](https://musicgpt.com/api-dashboard) your API Key. 2. Go to [Documentation](https://docs.musicgpt.com/api-documentation/index/introduction). 3. Inside features, you can click Try-it button to open a live [playground](https://docs.musicgpt.com/api-documentation/conversions/musicaiv2?playground=open). 4. You can also use the multi-language code samples provided for each feature to run it locally. 5. To get result: Set the [**webhook\_url**](https://docs.musicgpt.com/api-documentation/index/webhook) to an endpoint on your server or retrieve the result through our helper endpoint [**get conversion by id**](https://docs.musicgpt.com/api-documentation/endpoint/getById) instead. ## Available Features ### Music Generation Features 🎡 * **AI Music Generator**: Create original music from text prompts * **Custom Voice Music Generator**: Generate songs with AI vocals in different voice styles * **Cover Song**: Create AI-powered covers of existing songs * **Remix**: Transform tracks into new musical styles using AI ### Voice & Speech Features * **Text to Speech**: Convert text to natural-sounding speech * **Voice Changer**: Modify voices in existing audio to different characteristics ### Sound Design * **Sound Generator**: Create sound effects and audio elements from text prompts ### Extraction & Stem Separation #### Vocal Processing * **Vocal Extraction**: Isolate vocals from music tracks * **Gender-Based Vocal Extraction**: Separate male and female vocals * **Lead/Back Vocals Separation**: Split main vocals from backing harmonies #### Instrument Separation * **Instrumental Extraction**: Remove vocals to create instrumental versions * **Guitar Type Stems**: Separate acoustic and electric guitars * **Guitar Part Stems**: Isolate rhythm vs lead guitar parts * **Strings Stems**: Extract string instrument sections * **Keys Extraction**: Isolate piano and keyboard parts * **Winds Splitter**: Separate wind instruments #### Advanced Band Separation * **Band Parts Splitter**: Extract drums, bass, piano, and guitar stems * **Premium Bass/Drums Split**: High-accuracy rhythm section isolation * **Drum Stems Separation**: Separate individual drum components ### Audio Enhancement Features * **Voice Cleaner (Denoise)**: Remove background noise from audio * **DeEcho**: Eliminate echo effects * **DeReverb**: Reduce unwanted reverb * **Audio Cutter**: Trim and edit audio clips * **Speed Changer**: Adjust playback speed * **Audio Mastering**: Enhance overall sound quality * **File Converter**: Convert between audio formats ### Audio Analysis Features * **Key & BPM Detector**: Identify musical key and tempo * **Audio Transcription**: Convert speech to text with translation * **Audio to MIDI**: Transform audio into MIDI sequences *** ## Your First AI Song Let’s generate a **country song about our love for AI-generated music** We’ll use the `MUSIC_AI` feature with the following endpoint: ```http theme={null} POST https://api.musicgpt.com/api/public/v1/MusicAI ``` *** ## Example Request ```bash theme={null} curl -X 'POST' \ 'https://api.musicgpt.com/api/public/v1/MusicAI' \ -H 'accept: application/json' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Song about my love to AI Music in Country Style", "webhook_url": "https://webhook.yourwebsite.com" }' ``` > Replace `` with your actual API Key from your Musicgpt dashboard. ## Webhook Integration To get notified when the music generation is complete, we recommend setting up a webhook. This allows you to receive the URL of the generated song directly. > πŸ”— Set the `webhook_url` to an endpoint on your server β€” this is where Musicgpt will notify you once the generation is done. > Webhook receivers must use HTTPS; `http://` URLs are not accepted. > **Tip:** If you can’t use a webhook (e.g., code running on a user device), you can retrive the result through our helper endpoint [get conversion by id](/api-documentation/endpoint/getById) instead. *** ## Example Webhook Response ```json theme={null} { "success": true, "task_id": "string", "conversion_id": "string", "audio_url": "https://...", "conversion_cost": 1.0, "title": "string", "lyrics": "string", "prompt": "string", "music_style": "string" } ``` `audio_url` is a CDN URL that is valid for 1 day. Download the file within that window, or fetch a fresh URL from [get conversion by id](/api-documentation/endpoint/getById). *** ## πŸŽ‰ Mission Accomplished! You just generated your **first AI song** using the Musicgpt API. Now go make something amazing ✨ Need more help? Check out other endpoints and guides in the [documentation](/api-documentation/index/introduction)! # Sample Helper Request Source: https://docs.musicgpt.com/api-documentation/sample-get-request GET /v1/byId Retrieve details of a conversion using `task_id` or `conversion_id`. # Sample Conversion Request Source: https://docs.musicgpt.com/api-documentation/sample-post-request POST /v2/MusicAI Create music powered by AI using just a prompt, lyrics, or a defined music style. # Handling Errors Source: https://docs.musicgpt.com/api-documentation/utilities/error When interacting with our API, it's important to understand the different error codes that can occur during a request. These error codes help indicate what went wrong and can guide you in troubleshooting the issue. Below is a list of common error codes returned by the API, along with their descriptions and possible solutions. *** ## ❌ Common Error Codes | **Code** | **ERROR\_CODE** | **Description** | | - | - | - | | **400** | BAD\_REQUEST | The request is malformed or contains invalid parameters. Check that all required parameters are included and correctly formatted. | | **401** | UNAUTHORIZED\_ACCESS | The request does not include valid authorization. Check that your API key or credentials are correct and properly configured. | | **402** | INSUFFICIENT\_CREDITS | Your account has insufficient credits to process the request. Add credits or check your account balance. | | **403** | FORBIDDEN | Your plan or account entitlements do not permit the requested operation. Check your plan and feature access. | | **404** | RESOURCE\_NOT\_FOUND | The requested resource does not exist. Verify the endpoint, resource ID, and parameters. | | **409** | CONFLICT | The request conflicts with the current state of the resource, such as attempting to create a duplicate. Review the request and resource state. | | **422** | UNPROCESSABLE\_CONTENT | The request is understood, but the content cannot be processed or fails validation. Review the provided data for errors. | | **424** | FAILED\_DEPENDENCY | A required dependency failed while processing the request. Try again later or contact support if the issue persists. | | **429** | TOO\_MANY\_REQUESTS | You have exceeded the allowed request rate. Wait before retrying or reduce your request frequency. | | **500** | INTERNAL\_SERVER\_ERROR | An unexpected internal server error occurred. Try again later or contact support if the problem persists. | | **503** | SERVICE\_UNAVAILABLE | The service is temporarily unavailable. Try again later. | *** ## Error Response Format Error responses share the same JSON body. Use `error_code` to branch on the error type in your code, and `message` for details. ```json theme={null} { "success": false, "error_code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits to process this request." } ``` *** ## Error Handling Tips * **Check the Response Body**: The `error_code` and `message` fields tell you what went wrong and help you pinpoint the issue. * **Rate Limits**: If you encounter a **429** error, avoid sending requests too frequently. Implement exponential backoff to retry requests after waiting for the rate limit to reset. * **Authentication**: A **401** error means your API key is missing or invalid. A **403** error means your plan does not include the requested feature. Check your key and plan. * **Testing**: Always test your API calls in a controlled environment to ensure that the request format and parameters are correct. > πŸ“Œ **Tip:** Always handle errors gracefully in your application. Proper error handling ensures that users have a better experience, even when things go wrong! *** ## How to Handle Errors in Your Code It's good practice to incorporate error-handling logic in your API requests. Here's an example in Python for handling different types of errors: ### Python Example: ```python theme={null} import requests url = "https://api.musicgpt.com/api/public/v2/MusicAI" payload = { "prompt": "", "lyrics": "", "model": "v7", "webhook_url": "https://example.com/my-webhook" } headers = { "Authorization": "", "Content-Type": "application/json" } response = requests.post( url, json=payload, headers=headers) if response.status_code == 200: print("Request successful:", response.json()) else: try: error = response.json() error_code = error.get("error_code") message = error.get("message") except ValueError: error_code, message = None, response.text if error_code == "INSUFFICIENT_CREDITS": print("Add credits to your account:", message) elif error_code == "UNPROCESSABLE_CONTENT": print("Check your request parameters:", message) elif error_code == "TOO_MANY_REQUESTS": print("Rate limit exceeded, retry later:", message) else: print(f"{response.status_code} {error_code}:", message) ``` # Final Notes Source: https://docs.musicgpt.com/api-documentation/utilities/finalnotes Before you begin using the API, here are some essential reminders and best practices to ensure a smooth and efficient experience. *** ## βœ… Key Reminders ### 1. **Ensure Valid Request Parameters** It's important to double-check that all the parameters you're passing in the API requests are valid. Invalid parameters can lead to errors or unexpected behavior. Always refer to the documentation for the correct formats and required fields. ### 2. **Handle All Responses and Errors Appropriately** The API may return different types of responses, including success and error messages. It's essential to handle both correctly: * **Success Responses**: Make sure to process the data as needed, whether it’s metadata or a direct link to the generated audio file. * **Error Responses**: Always account for error codes (like `400` for bad requests or `429` for rate limits exceeded). Implement proper error handling mechanisms to retry or notify users in case of failures. ### 3. **Use Webhook URLs for Asynchronous Responses** Many API endpoints, especially those related to audio generation or large files, are asynchronous. This means you won’t receive the final output immediately. In such cases, use **webhook URLs** to receive a callback when the process is complete. This helps automate the process and improves efficiency. *** ## πŸ”§ Best Practices * **Monitor API Usage**: Keep an eye on your usage, especially if you have an application that makes frequent requests. Monitor how many requests you are making in real-time to avoid hitting the rate limits. * **Optimize Request Handling**: If you have multiple tasks, batch them together to make fewer API calls. For instance, if you're retrieving conversion statuses for multiple requests, try to use the batch processing feature if available. * **Gracefully Handle Errors**: Implement retry logic, exponential backoff strategies, and user notifications in case of failures. This will make your application more robust. *** ## πŸ“¬ Feedback and Support If you run into any issues or have specific questions, don't hesitate to reach out to the API support team at: [api@musicgpt.com](mailto:api@musicgpt.com). Providing detailed logs of any errors you're facing will help resolve issues faster. > 🚨 **Reminder**: Always test with small requests first and gradually scale up to avoid running into rate limits or unexpected behavior. *** Thank you for using the API! We hope it helps you create amazing music and audio experiences. # Prompt Guidelines Source: https://docs.musicgpt.com/api-documentation/utilities/prompt_guideline Learn how to write effective prompts and lyrics for the best MusicGPT results. To get the best results, follow these guidelines: * Keep prompts descriptive and simple. * **Prompt limit:** 1000 characters. * **Lyrics limit:** 5000 characters. * **Exception:** Sound Generator prompts are capped at 300 characters, because they describe short sound effects rather than songs. * You can describe song sections like this: * `[Intro – soft piano and light synths]` * `[Chorus – repeat with more intensity]` * `[Bridge – add soft strings or a subtle beat drop]` * Do not include any artist names in the `prompt` or `lyrics` fields. ## Best Practice * **If you provide `lyrics`:** Use `prompt` to describe the complete song. You can also use section tags inside `lyrics` to guide the arrangement and performance. * **If `lyrics` is empty:** Use `prompt` to describe the song’s genre, vibe, instrumentation, and context. * **Content Moderation** : All requests are internally analyzed for content safety and policy compliance before generation. Please avoid using **NSFW content, hate speech, violence, self-harm, or copyrighted references**. # Ratelimits Source: https://docs.musicgpt.com/api-documentation/utilities/ratelimits | Category | Features | Free Plan | Plus Plan | Pro Plan | | - | - | - | - | - | | Audio Generations | [Music AI](/api-documentation/conversions/musicaiv2)
[Inpaint](/api-documentation/conversions/inpaint)
[Remix](/api-documentation/conversions/remix)
[Extend](/api-documentation/conversions/extend)
[Sing Over Instrumental](/api-documentation/conversions/sing_over_instrumental) | 1 parallel requests | 3 parallel requests | 10 parallel requests | | Audio Utilities | [File Convert](/api-documentation/conversions/fileconvert)
[Audio to MIDI](/api-documentation/conversions/audiotomidi)
[Audio Cutter](/api-documentation/conversions/audiocutter)
[Audio Speed Changer](/api-documentation/conversions/audiospeedchanger)
[Audio Mastering](/api-documentation/conversions/audiomastering)
[Key/BPM Extraction](/api-documentation/conversions/extractkeybpm) | 1 parallel requests | 3 parallel requests | 10 parallel requests | | Audio Enhancements | [Text\_To\_Speech](/api-documentation/conversions/texttospeech)
[Voice\_Changer](/api-documentation/conversions/voicechanger)
[Extraction](/api-documentation/conversions/extraction)
[Cover](/api-documentation/conversions/cover)
[Denoising](/api-documentation/conversions/denoise)
[Deecho](/api-documentation/conversions/deecho)
[Dereverb](/api-documentation/conversions/dereverb)
[Sound\_Generator](/api-documentation/conversions/soundgenerator)
[Audio\_Transcribe](/api-documentation/conversions/audiotranscription)
[Lyrics\_Generator](/api-documentation/conversions/lyrics_generator) | 1 parallel requests | 3 parallel requests | 10 parallel requests | | Get by ID | [Get by ID](/api-documentation/endpoint/getById) | 20 API calls per minute | 200 API calls per minute | 500 API calls per minute | ### Rate Limit * **Limit:** Maximum parallel audio creation requests per plan β€” **1** on Free, **3** on Plus, and **10** on Pro.
**What This Means:** You can send up to your plan’s number of concurrent requests across all features combined for a given category. If you reach this limit, you must wait for some requests to complete before sending additional requests. Requests to other categories are not affected by this limit and can be sent independently. ### Sound Generator Free Period * **Limit:** During October 2026, [Sound Generator](/api-documentation/conversions/soundgenerator) is free, up to **500 generations per day** and **21 generations per hour**. ### Audio Length Limits Maximum length of the input audio you can send, per feature: | Feature | Max input audio length | | - | - | | [Remix](/api-documentation/conversions/remix), [Extend](/api-documentation/conversions/extend), [Inpaint](/api-documentation/conversions/inpaint), [Sing Over Instrumental](/api-documentation/conversions/sing_over_instrumental) | 4 minutes | | All other features | 8 minutes |