> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace Music Section
> Replace a specific time segment within existing music.
### Parameter Usage Guide
This endpoint supports two modes for specifying the source audio:
**Mode 1: Replace section using existing audio**
* `taskId` and `audioId` are required
* `uploadUrl` and `model` must NOT be provided
**Mode 2: Replace section using uploaded custom audio**
* `uploadUrl` and `model` are required
* `taskId` and `audioId` must NOT be provided
### Common Required Parameters
* **prompt** (string, required): Replaced lyrics
* **tags** (string, required): Music style tags, such as jazz, electronic, etc.
* **title** (string, required): Music title
* **infillStartS** (number, required): Start time point for replacement (seconds, 2 decimal places)
* **infillEndS** (number, required): End time point for replacement (seconds, 2 decimal places)
* **fullLyrics** (string, required): Complete lyrics after modification, combining both modified and unmodified lyrics
### Optional Parameters
The following fields are optional controls available for this endpoint:
* negativeTags (string): Excluded music styles, used to avoid specific style elements in the replacement segment
* callBackUrl (string): Callback URL for task completion notification. For detailed callback format, see [Replace Music Section Callbacks](/suno-api/replace-section-callbacks).
### 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
```json Replace using existing audio theme={null}
{
"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"
}
```
```json Replace using uploaded audio theme={null}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V4",
"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"
}
```
### Developer Notes
1. Replacement segments will be regenerated based on the provided `prompt` and `tags`
2. Generated replacement segments will automatically blend with the original music's preceding and following parts
3. Generated files will be retained for **14 days**
4. Query task status using the same interface as generating music: [Get Music Details](/suno-api/get-music-generation-details)
## OpenAPI
````yaml suno-api/suno-api.json POST /api/v1/generate/replace-section
openapi: 3.0.0
info:
title: intro
description: API documentation for audio generation services
version: 1.0.0
contact:
name: Technical Support
email: support@api.box
servers:
- url: https://apibox.erweima.ai
description: API Server
security:
- BearerAuth: []
tags:
- name: Music Generation
description: Endpoints for creating and managing music generation tasks
- name: Lyrics Generation
description: Endpoints for lyrics generation and management
- name: WAV Conversion
description: Endpoints for converting music to WAV format
- name: Vocal Removal
description: Endpoints for vocal removal from music tracks
- name: Music Video Generation
description: Endpoints for generating MP4 videos from music tracks
- name: Account Management
description: Endpoints for account and credits management
paths:
/api/v1/generate/replace-section:
post:
summary: Replace Music Section
description: >-
Replace a specific time segment within existing music.
> Replace a specific time segment within existing music.
This interface can replace specific time segments in already generated
music. It 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.
## 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](/suno-api/get-music-generation-details).
operationId: replace-section
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- prompt
- tags
- title
- infillStartS
- infillEndS
- fullLyrics
oneOf:
- title: Replace section using existing audio
required:
- taskId
- audioId
properties:
taskId:
type: string
description: >-
Original task ID (parent task), used to identify the
source music for section replacement.
example: 2fac****9f72
audioId:
type: string
description: >-
Unique identifier of the audio track to replace. This ID
is returned in the callback data after music generation
completes.
example: e231****-****-****-****-****8cadc7dc
- title: Replace section using uploaded custom audio
required:
- uploadUrl
- model
properties:
uploadUrl:
type: string
format: uri
description: URL of the custom audio uploaded by the user.
example: https://example.com/audio.mp3
model:
type: string
description: |-
AI model version used for generation.
- Available options:
- **`V5_5`**: A tailor-made exclusive model that fits your unique taste.
- **`V5`**: Better musical expressiveness with faster generation speed.
- **`V4_5PLUS`**: V4.5+ with richer timbre, new creative methods, up to 8 minutes.
- **`V4_5`**: V4.5 with smarter prompts, faster generation speed, up to 8 minutes.
- **`V4_5ALL`**: V4.5ALL with smarter prompts, faster generation speed, up to 8 minutes.
- **`V4`**: V4 with improved vocal quality, up to 4 minutes.
enum:
- V4
- V4_5
- V4_5PLUS
- V4_5ALL
- V5
- V5_5
example: V4
properties:
prompt:
type: string
description: Replaced lyrics
example: A calm and relaxing piano track.
tags:
type: string
description: Music style tags, such as jazz, electronic, etc.
example: Jazz
title:
type: string
description: Music title
example: Relaxing Piano
negativeTags:
type: string
description: >-
Excluded music styles, used to avoid specific style elements
in the replacement segment
example: Rock
infillStartS:
type: number
description: >-
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.
minimum: 0
example: 10.5
infillEndS:
type: number
description: >-
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.
minimum: 0
example: 20.75
fullLyrics:
type: string
description: >-
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]
Original lyrics here
[Chorus]
Modified lyrics for this section
[Verse 2]
More original lyrics
callBackUrl:
type: string
format: uri
description: >-
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](/suno-api/replace-section-callbacks)
- Alternatively, you can use the get music details interface
to poll task status
example: https://example.com/callback
example:
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]
Original lyrics here
[Chorus]
Modified lyrics for this section
[Verse 2]
More original lyrics
callBackUrl: https://example.com/callback
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: >-
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
msg:
type: string
description: Error message when code != 200
example: success
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: >-
Task ID for tracking task status. You can use this
ID to query task details and results through the
"Get Music Details" interface.
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: >-
When audio generation is complete, the system will call this
callback to notify the result.
### Callback Example
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "e231****-****-****-****-****8cadc7dc",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"prompt": "A calm and relaxing piano track.",
"model_name": "chirp-v3-5",
"title": "Relaxing Piano",
"tags": "Jazz",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Status code
example: 200
msg:
type: string
description: Return message
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
Callback type: text (text generation complete),
first (first song complete), complete (all
complete)
enum:
- text
- first
- complete
task_id:
type: string
description: Task ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: Audio unique identifier (audioId)
audio_url:
type: string
description: Audio file URL
stream_audio_url:
type: string
description: Streaming audio URL
image_url:
type: string
description: Cover image URL
prompt:
type: string
description: Generation prompt/lyrics
model_name:
type: string
description: Model name used
title:
type: string
description: Music title
tags:
type: string
description: Music tags
createTime:
type: string
description: Creation time
format: date-time
duration:
type: number
description: Audio duration (seconds)
responses:
'200':
description: Callback received successfully
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: >-
Response status code
- **200**: Success - Request processed
successfully
- **400**: Validation error - Lyrics contain
copyrighted content.
- **408**: Rate limit exceeded - Timeout.
- **413**: Conflict - Uploaded audio matches
existing artwork.
- **500**: Server error - Unexpected error
occurred while processing request
- **501**: Audio generation failed.
- **531**: Server error - Sorry, generation
failed due to issues. Your credits have been
refunded. Please try again.
msg:
type: string
description: Error message when code != 200
example: success
example:
code: 200
msg: success
method: post
type: path
path: '{request.body#/callBackUrl}'
components:
responses:
Error:
description: Server error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
# 🔑 API Authentication
All endpoints require authentication using Bearer Token.
## Get API Key
1. Visit the [API Key Management Page](https://api.box/api-key) 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
````