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 always uses custom parameters. Simple mode is not available. 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. 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 after modification, combining both modified and unmodified lyrics

​
Lyrics Fields

Three fields carry lyrics, each with a different scope:
  • fullLyrics (required): the complete lyrics of the whole song after the replacement, combining modified and unmodified parts. The upstream service uses it to re-align the prompt for the infill segment.
  • lyrics (optional): lyrics for the replaced segment only.
  • prompt (required): the replaced lyrics, kept for backward compatibility.

​
Optional Parameters

The following fields are optional controls available for this endpoint:
  • lyrics (string): Lyrics for the replaced section. For V6, V6_WILD, and V6_MINI: maximum 5000 characters.
  • 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 (integer): 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 to apply to the generated music. If you use a Voice-generated ID, set personaModel to voice_persona.
  • personaModel (string): Persona type, default style_persona. Use style_persona for Generate Persona IDs, or voice_persona for Suno Voice IDs.
  • 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 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

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

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

​
negativeTags
string

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

Example:

"Rock"

​
lyrics
string

Lyrics for the replaced section. Optional. fullLyrics carries the complete lyrics of the whole song, while lyrics covers only the segment being replaced.

  • V6, V6_WILD & V6_MINI: Maximum 5000 characters
Example:

"[Chorus] Brighter lights, we keep going on"

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

​
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. Two decimal places recommended.

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

0.61

​
weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.

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

0.72

​
audioWeight
number

Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.

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

0.65

​
variety
integer
default:1

Diversity of generated results. Optional. Integer from 0 to 4. Default: 1.

  • 0: off — variety off, strictly the same style
  • 1: normal — default, balances stability and diversity
  • 2: high — results with clearly different styles
  • 3: extra — higher variation, bolder exploration
  • 4: max — maximum variation
Required range: 0 <= x <= 4Must be a multiple of 1
Example:

1

​
personaId
string

Persona ID to apply to the generated music. Optional. You can use either:

  • A Persona ID generated by the Generate Persona endpoint. Use personaModel: style_persona or omit personaModel to use the default.
  • A voiceId generated by the Suno Voice workflow. When using a voice-generated ID, you must set personaModel: voice_persona.
Example:

"persona_123"

​
personaModel
enum<string>
default:style_persona

Persona model type to apply when using personaId. Optional.

  • style_persona (default): Use this for Persona IDs generated by the Generate Persona endpoint.
  • voice_persona: Required when personaId is a voiceId generated by Suno Voice. This option is only available with V5 (Deprecated), V5_5 (Deprecated), V6, V6_WILD, and V6_MINI models.
Available options:
style_persona,
voice_persona
Example:

"style_persona"

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