Skip to main content
POST
/
api
/
v1
/
generate
/
replace-section
Replace Music Section
curl --request POST \
  --url https://api.sunoapi.org/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,
  "callBackUrl": "https://example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt

Use this file to discover all available pages before exploring further.

​
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
    • 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.

Example:

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

​
prompt
string
required

Replaced lyrics

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"

​
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