Skip to main content
POST
/
api
/
v1
/
generate
/
replace-section
Replace Music Section
curl --request POST \
  --url https://api.api.box/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",
  "infillStartS": 10.5,
  "infillEndS": 20.75,
  "negativeTags": "Rock",
  "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 (selected from the generated music list)
    • 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

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

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 from 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

Audio ID of the track to replace. This identifies which specific audio from the generated music list will have its section replaced.

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