Skip to main content
POST
/
api
/
v1
/
generate
/
replace-section
Replace Music Section
curl --request POST \
  --url https://api.kie.ai/api/v1/generate/replace-section \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taskId": "2fac****9f72",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "prompt": "A calm and relaxing piano track.",
  "tags": "Jazz",
  "title": "Relaxing Piano",
  "negativeTags": "Rock",
  "infillStartS": 10.5,
  "infillEndS": 20.75,
  "fullLyrics": "[Verse 1]\nOriginal lyrics here\n[Chorus]\nModified lyrics for this section\n[Verse 2]\nMore original lyrics",
  "callBackUrl": "https://example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Usage Guide

  • This interface can replace specific time segments in already generated music
  • Requires providing the original music’s task ID and the time range to be replaced
  • The replaced audio will naturally blend with the original music

​
Parameter Details

  • Required Parameters:
    • taskId: Original music’s parent task ID
    • audioId: Audio ID to replace
    • prompt: Prompt describing the replacement segment content
    • tags: Music style tags
    • title: Music title
    • infillStartS: Start time point for replacement (seconds, 2 decimal places)
    • infillEndS: End time point for replacement (seconds, 2 decimal places)
  • Optional Parameters:
    • negativeTags: Music styles to exclude
    • fullLyrics: Complete lyrics after modification, combining both modified and unmodified lyrics
    • callBackUrl: Callback address after task completion

​
Time Range Instructions

  • infillStartS must be less than infillEndS
  • Time values are precise to 2 decimal places, e.g., 10.50 seconds
  • The replacement time range must be between 6 and 60 seconds
  • Replacement duration should not exceed 50% of the original music’s total duration

​
Developer Notes

  • Replacement segments will be regenerated based on the provided prompt and tags
  • Generated replacement segments will automatically blend with the original music’s preceding and following parts
  • Generated files will be retained for 14 days
  • Query task status using the same interface as generating music: Get Music Details

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
​
taskId
string
required

Original task ID (parent task), used to identify the source music for section replacement

Example:

"2fac****9f72"

​
audioId
string
required

Unique identifier of the audio track to replace. This ID is returned in the callback data after music generation completes.

Example:

"e231****-****-****-****-****8cadc7dc"

​
prompt
string
required

Prompt for generating the replacement segment, typically text describing the audio content

Example:

"A calm and relaxing piano track."

​
tags
string
required

Music style tags, such as jazz, electronic, etc.

Example:

"Jazz"

​
title
string
required

Music title

Example:

"Relaxing Piano"

​
infillStartS
number
required

Start time point for replacement (seconds), 2 decimal places. Must be less than infillEndS. The time interval (infillEndS - infillStartS) must be between 6 and 60 seconds.

Required range: x >= 0
Example:

10.5

​
infillEndS
number
required

End time point for replacement (seconds), 2 decimal places. Must be greater than infillStartS. The time interval (infillEndS - infillStartS) must be between 6 and 60 seconds.

Required range: x >= 0
Example:

20.75

​
negativeTags
string

Excluded music styles, used to avoid specific style elements in the replacement segment

Example:

"Rock"

​
fullLyrics
string

Complete lyrics after modification, combining both modified and unmodified lyrics. This parameter contains the full lyrics text that will be used for the entire song after the section replacement.

Example:

"[Verse 1]\nOriginal lyrics here\n[Chorus]\nModified lyrics for this section\n[Verse 2]\nMore original lyrics"

​
callBackUrl
string<uri>

Callback URL for task completion. The system will send a POST request to this URL when replacement is complete, containing task status and results.

  • Your callback endpoint should be able to accept POST requests containing JSON payloads with replacement results
  • For detailed callback format and implementation guide, see Replace Music Section Callbacks
  • Alternatively, you can use the get music details interface to poll task status
Example:

"https://example.com/callback"

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request processed successfully
  • 401: Unauthorized - Authentication credentials missing or invalid
  • 402: Insufficient credits - Account does not have enough credits to perform this operation
  • 404: Not found - Requested resource or endpoint does not exist
  • 409: Conflict - WAV record already exists
  • 422: Validation error - Request parameters failed validation checks
  • 429: Rate limit exceeded - Exceeded request limit for this resource
  • 451: Unauthorized - Failed to retrieve image. Please verify any access restrictions set by you or your service provider.
  • 455: Service unavailable - System is currently undergoing maintenance
  • 500: Server error - Unexpected error occurred while processing request
Available options:
200,
401,
402,
404,
409,
422,
429,
451,
455,
500
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object