Skip to main content
POST

​
Model Versions

  • Current models: V6 (default), V6_WILD, V6_MINI
  • Deprecated models: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4
  • Deprecated values remain available only for backward compatibility. New integrations should use a V6-series model.

​
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
This endpoint always runs in custom mode.

​
Common Required Parameters

  • prompt (string, required): Lyrics for the replaced segment. If lyrics is also provided, lyrics takes priority for the replaced segment.
  • 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. Must be less than infillEndS. The time interval (infillEndS - infillStartS) must be at least 10 seconds.
  • infillEndS (number, required): End time point for replacement (seconds), 2 decimal places. Must be greater than infillStartS. The time interval (infillEndS - infillStartS) must be at least 10 seconds.
  • fullLyrics (string, required): Complete lyrics of the whole song after modification, combining both modified and unmodified lyrics. Distinct from lyrics/prompt, which apply only to the replaced segment.

​
Optional Parameters

The following fields are optional controls available for this endpoint:
  • lyrics (string): Lyrics for the replaced segment. Optional. V6 series maximum 5000 characters. Takes priority over prompt for the replaced segment. Distinct from fullLyrics, which is the complete song lyrics.
  • negativeTags (string): Excluded music styles, used to avoid specific style elements in the replacement segment
  • vocalGender (string): Preferred vocal gender. Allowed values: m (male), f (female)
  • styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
  • weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
  • audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
  • variety (number): Diversity of generated results. Integer from 0–4, default 1. 0 off, 1 normal (default), 2 high, 3 extra, 4 max.
  • personaId (string): Persona ID or Suno Voice voiceId. If you use a Voice-generated ID, set personaModel to voice_persona.
  • personaModel (string): Persona type. Use style_persona for Generate Persona IDs, or voice_persona for Suno Voice IDs. Default style_persona.
  • callBackUrl (string): Callback URL for task completion notification. For detailed callback format, see Replace Music 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 must be at least 10 seconds.
  • Replacement duration should not exceed 50% of the original music’s total duration

​
Developer Notes

  1. Replacement segments will be regenerated based on the provided lyrics/prompt and tags. Use lyrics (or prompt) for the replaced segment and fullLyrics for the complete song.
  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

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:

⚠️ 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

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

Lyrics for the replaced segment. Required. If lyrics is also provided, lyrics takes priority for the replaced segment.

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 at least 10 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 at least 10 seconds.

Required range: x >= 0
Example:

20.75

​
fullLyrics
string
required

Complete lyrics of the whole song after modification, combining both modified and unmodified lyrics. Distinct from lyrics (and prompt), which apply only to the replaced segment. This field is the full lyrics text 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"

​
lyrics
string

Lyrics content. Optional. For V6, V6_MINI, and V6_WILD: maximum 5000 characters. Lyrics for the replaced segment only. Distinct from fullLyrics, which is the complete song lyrics.

Example:

"[Verse] Night city lights shining bright"

​
negativeTags
string

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

Example:

"Rock"

​
vocalGender
enum<string>

Preferred vocal gender. Optional. Allowed values: m (male), f (female).

Available options:
m,
f
Example:

"m"

​
styleWeight
number

Style adherence weight. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
audioWeight
number

Relative weight of audio consistency versus other controls. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
variety
number
default:1

Controls the diversity and stylistic variation of generated results. Optional. Integer from 0–4, default 1.

  • 0: off (exact style) — fully off, strictly the same style
  • 1: normal (balanced variety) — default, balances stability and diversity
  • 2: high (distinct styles) — produces results with clearly different styles
  • 3: extra (bold exploration) — higher variation, encourages bold exploration of different styles
  • 4: max (unreasonably varied) — maximum diversity; results may differ in style very significantly
Required range: 0 <= x <= 4Must be a multiple of 1
Example:

1

​
personaId
string

Persona ID or Voice ID to apply to the generated music. Optional. When using a Voice-generated ID, set personaModel to voice_persona.

Example:

"persona_123"

​
personaModel
enum<string>
default:style_persona

Persona model type. Optional. style_persona (default) for Generate Persona IDs; voice_persona when personaId is a Suno Voice voiceId. Default style_persona.

Available options:
style_persona,
voice_persona
Example:

"style_persona"

​
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"

Callbacks

POST
{request.body#/callBackUrl}audioGenerated

Body

application/json
​
code
integer

Status code

Example:

200

​
msg
string

Return message

Example:

"All generated successfully"

​
data
object

Response

200 - application/json

Callback received successfully

​
code
enum<integer>

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.
Available options:
200,
400,
408,
413,
500,
501,
531
​
msg
string

Error message when code != 200

Example:

"success"

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