Replace Music Section
Replace a specific time segment within existing music.
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 IDaudioId: Audio ID to replaceprompt: Prompt describing the replacement segment contenttags: Music style tagstitle: Music titleinfillStartS: 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 excludefullLyrics: Complete lyrics after modification, combining both modified and unmodified lyricscallBackUrl: Callback address after task completion
Time Range Instructions
infillStartSmust be less thaninfillEndS- 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
promptandtags - 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
Rate limits and quotas are enforced by Apikley and may differ from upstream providers.
OpenAPI
suno-api/suno-api.json post /api/v1/generate/replace-section
openapi: 3.0.0
info:
title: Suno API
description: Apikley Suno API Documentation
version: 1.0.0
contact:
name: Technical Support
email: support@apikley.ru
servers:
- url: https://api.apikley.ru
description: API Server
security:
- BearerAuth: []
paths:
/api/v1/generate/replace-section:
post:
summary: Replace Music Section
description: >-
Replace a specific time segment within existing music. This interface
allows you to select a specific segment of music for regeneration and
replacement.
### 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
- `taskId`: Required parameter, original music's parent task ID
- `audioId`: Required parameter, audio ID to replace
- `prompt`: Required parameter, prompt describing the replacement
segment content
- `tags`: Required parameter, music style tags
- `title`: Required parameter, music title
- `infillStartS`: Required parameter, start time point for replacement
(seconds, 2 decimal places)
- `infillEndS`: Required parameter, end time point for replacement
(seconds, 2 decimal places)
- `negativeTags`: Optional parameter, music styles to exclude
- `callBackUrl`: Optional parameter, callback address after task
completion
- `fullLyrics`: Optional parameter, complete lyrics after modification,
combining both modified and unmodified lyrics
### Time Range Instructions
- `infillStartS` must be less than `infillEndS`
- Time values are precise to 2 decimal places, e.g., 10.50 seconds
- The time interval between `infillStartS` and `infillEndS` 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
operationId: replace-section
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- taskId
- audioId
- prompt
- tags
- title
- infillStartS
- infillEndS
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
prompt:
type: string
description: >-
Prompt for generating the replacement segment, typically
text describing the audio content
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.
example: 10.5
minimum: 0
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.
example: 20.75
minimum: 0
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](https://docs.apikley.ru/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
components:
responses:
Error:
description: Server Error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
All APIs require authentication via Bearer Token.
Get API Key:
1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
API Key
Usage:
Add to request header:
Authorization: Bearer APIKLEY_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
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt