Inpaint - Musicgpt API Documentation

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",
  "num_outputs": 1,
  "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
}

POST

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",
  "num_outputs": 1,
  "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

Parameter	Type	Required	Description
`audio_file`	`UploadFile`	Optional	Upload the input audio file. Required if `audio_url` is not provided.
`audio_url`	`String`	Optional	Public/S3/YouTube URL of the input audio. Required if `audio_file` is not provided.
`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 : 1).
`webhook_url`	`String`	Optional	Callback 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 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.

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

Option 1
Option 2

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"

num_outputs

number<integer>

The number of outputs to generate (1 or 2 only):default is 2.

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>

Extend Lyrics Generator

​Endpoint

​Request Parameters

​Sample Output

​Try it Yourself

​Sample Request

​cURL

​Python

​Sample Response

​Success (200 OK)

​Webhook Delivery

​Standard Requests (non-instrumental):

​Common Errors

​Payload and Request Formation

Authorizations

Body

Response

Endpoint

Request Parameters

Sample Output

Try it Yourself

Sample Request

cURL

Python

Sample Response

Success (200 OK)

Webhook Delivery

Standard Requests (non-instrumental):

Common Errors

Payload and Request Formation