Skip to main content
POST
/
v1
/
inpaint
Python
import requests

url = "https://api.musicgpt.com/api/public/v1/inpaint"
headers = {"Authorization": "<API_KEY>"}
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",
  "webhook_url": "https://example.com/webhook"
}

# Option 1: audio_url
data["audio_url"] = "https://mybucket.s3.amazonaws.com/song.mp3"
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())
{
  "success": true,
  "message": "Inpaint request submitted successfully",
  "task_id": "task-xyz-123",
  "conversion_id_1": "inpaint-abc",
  "conversion_id_2": "inpaint-def",
  "eta": 40,
  "credit_estimate": 45
}
Replace a specific segment of an audio file using a prompt and optional lyrics.

​
Endpoint

POST /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

ParameterTypeRequiredDescription
audio_fileUploadFileOptionalUpload the input audio file. Required if audio_url is not provided.
audio_urlStringOptionalPublic/S3/YouTube URL of the input audio. Required if audio_file is not provided.
promptStringRequiredPrompt describing how the replacement should sound. Example: “Replace this part with an opera-style vocal.”
replace_start_atFloatRequiredStart time (in seconds) of the segment to replace.
replace_end_atFloatRequiredEnd time (in seconds) of the segment to replace.
lyricsStringOptionalOriginal lyrics of song.
lyrics_section_to_replaceStringOptionalLyrics to be used for the replaced portion(optional, max 3000 characters)
genderStringOptionalVoice style for vocal generation. One of: male, female, neutral.
webhook_urlStringOptionalCallback URL for async response.
💡 Note: You must provide either audio_file or audio_url — at least one is required.
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 to test the endpoint — set your payload, hit send, and view the generated results.

​
Sample Request

​
cURL

curl -X POST "https://api.musicgpt.com/api/public/v1/inpaint" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-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

import requests

url = "https://api.musicgpt.com/api/public/v1/inpaint"
headers = {"Authorization": "<API_KEY>"}
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",
    "gender": "male",
    "webhook_url": "https://example.com/webhook"
}

# Option 1: URL
files = {}
data["audio_url"] = "https://mybucket.s3.amazonaws.com/track.mp3"
response = requests.post(url, headers=headers, data=data, files=files)

# 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())
🔐 Replace {path_to_your_audio_file}, api_key, and webhook_url before executing.

​
Sample Response

​
Success (200 OK)

{
  "success": true,
  "message": "Inpaint request submitted successfully",
  "task_id": "task-xyz-123",
  "conversion_id_1": "inpaint-abc",
  "conversion_id_2": "inpaint-def",
  "eta": 40,
  "credit_estimate": 45
}

​
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
Webhook responses include detailed metadata including task_id, conversion_id, audio files (conversion_path), lyrics etc.

​
Common Errors

  • 422 Unprocessable Entity: Missing required fields like prompt, replace_start_at, or replace_end_at, or neither audio_file nor audio_url provided.
  • 500 Internal Server Error: An unexpected error occurred during processing.
The response provides a downloadable or streamable inpainted audio file.

​
Payload and Request Formation

Authorizations

​
Authorization
string
header
required

Body

multipart/form-data
​
audio_url
string
required

URL or S3 path to the input audio.

Example:

"https://mybucket.s3.amazonaws.com/song.mp3"

​
prompt
string
required

A description of how the replacement should sound.

Example:

"Replace this part with an opera-style vocal."

​
replace_start_at
number<float>
required

Time in seconds to start replacing audio.

Example:

12.5

​
replace_end_at
number<float>
required

Time in seconds to stop replacing audio.

Example:

20

​
audio_file
file

Uploaded input audio file.

​
lyrics
string

Lyrics to be used for inpainting.

Example:

"This is where my story begins"

​
lyrics_section_to_replace
string

Lyrics to be used for the replaced portion(optional, max 3000 characters)

Maximum string length: 2000
​
gender
enum<string>

Voice style for the inpainted segment.

Available options:
male,
female,
neutral
Example:

"male"

​
webhook_url
string

Callback URL for async processing results.

Example:

"https://example.com/webhook"

Response

Successfully initiated inpaint task

​
success
boolean
​
message
string
​
task_id
string
​
conversion_id_1
string
​
conversion_id_2
string
​
eta
integer

Estimated processing time in seconds

​
credit_estimate
number<float>