Skip to main content
POST

​
Parameter Usage Guide

  • instrumental (boolean, optional) determines whether to generate instrumental music and defaults to false.
  • prompt is optional in all modes and for all instrumental values.
  • When defaultParamFlag is true (Custom Parameters):
    • If instrumental is true: only style, title, and uploadUrl are required; prompt and vocalGender are optional.
    • If instrumental is false: only style, title, and uploadUrl are required. prompt is optional and is used as the prompt when provided; vocalGender is optional.
    • Character limits (based on model):
      • V4_5, V4_5PLUS, V5, V5_5 models: prompt max 5000 characters, style max 1000 characters, title max 100 characters
      • V4 model: prompt max 3000 characters, style max 200 characters, title max 80 characters
      • V4_5ALL model: prompt max 5000 characters, style max 1000 characters, title max 80 characters
    • model (string, required): V4_5ALL, V4, V4_5, V4_5PLUS, V5, V5_5. V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same limits as V5 where applicable.
    • continueAt: the time point in seconds from which to start extending (must be greater than 0 and less than the uploaded audio duration)
    • uploadUrl: specifies the upload location for audio files; ensure uploaded audio does not exceed 8 minutes.
  • When defaultParamFlag is false (Default Parameters):
    • Only uploadUrl is required
    • prompt is optional
    • If instrumental is false, lyrics will be generated automatically
    • Other parameters will use the original audio’s parameters

​
Optional parameters

The following fields are optional controls available for this endpoint:
  • vocalGender (string): Optional and not required whether instrumental is true or false. 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)
  • personaId (string): Persona ID or Suno Voice voiceId to apply when using custom parameters. 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.

​
Developer Notes

  1. Generated files will be retained for 14 days
  2. Model version must be consistent with the source music
  3. This feature is ideal for creating longer works by extending existing music
  4. Pay attention to character limits for prompt, style, and title to ensure successful processing
  5. uploadUrl parameter specifies the upload location for audio files; provide a valid URL.

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
​
uploadUrl
string<uri>
required

The URL for uploading audio files, required regardless of whether defaultParamFlag is true or false. Ensure the uploaded audio does not exceed 8 minutes in length.

Example:

"https://storage.example.com/upload"

​
defaultParamFlag
boolean
required

Enables custom mode for advanced audio generation settings.

  • Set to true to use custom parameter mode (requires style, title, and uploadUrl). prompt is optional in all cases and, when provided, is used as a prompt.
  • Set to false to use non-custom mode (only uploadUrl is required). prompt remains optional. When instrumental is false, lyrics are generated automatically.
Example:

true

​
model
enum<string>
required

The AI model version to use for generation.

  • Required for all requests.
  • Available options:
    • V5: Superior musical expression, faster generation.
    • V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. Same custom-mode prompt and style character limits as V5 (5000 / 1000).
    • V4_5PLUS: V4.5+ is richer sound, new waysto create, max 8 min.
    • V4_5: V4.5 is smarter prompts, fastergenerations, max 8 min.
    • V4: V4 is improved vocal quality,max 4 min.
    • V4_5ALL: V4.5-all is better song structure,max 8 min.
Available options:
V4_5ALL,
V4,
V4_5,
V4_5PLUS,
V5,
V5_5
Example:

"V4_5ALL"

​
callBackUrl
string<uri>
required

The URL to receive task completion notifications when upload and extend audio is complete. The callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete). Note: In some cases, text and first stages may be skipped, directly returning complete.

  • For detailed callback format and implementation guide, see Upload and Extend Audio Callbacks
  • Alternatively, you can use the Get Music Generation Details interface to poll task status
Example:

"https://api.example.com/callback"

​
instrumental
boolean
default:false

Determines whether the audio should be instrumental (without lyrics).

  • In custom parameter mode (defaultParamFlag: true):
    • If true: only style, title, and uploadUrl are required; prompt and vocalGender do not need to be provided.
    • If false: style, title, and uploadUrl are required; prompt is optional and, when provided, is used as a prompt; vocalGender does not need to be provided.
  • In non-custom parameter mode (defaultParamFlag: false): required fields are unaffected (only uploadUrl is required), and prompt remains optional. If false, lyrics are generated automatically.
    Optional. Defaults to false.
Example:

false

​
prompt
string

Describes how the music should be extended. Optional in all cases. When provided, it is used as a prompt. Character limits by model:

  • V4: Maximum 3000 characters
  • V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 5000 characters
Example:

"Extend the music with more relaxing notes"

​
style
string

Music style, e.g., Jazz, Classical, Electronic. Character limits by model:

  • V4: Maximum 200 characters
  • V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL: Maximum 1000 characters
Example:

"Classical"

​
title
string

Music title. Character limits by model:

  • V4 & V4_5ALL: Maximum 80 characters
  • V4_5, V4_5PLUS, V5 & V5_5: Maximum 100 characters
Example:

"Peaceful Piano Extended"

​
continueAt
number

The time point (in seconds) from which to start extending the music.

  • Required when defaultParamFlag is true.
  • Value range: greater than 0 and less than the total duration of the uploaded audio.
  • Specifies the position in the original track where the extension should begin.
Example:

60

​
personaId
string

Only available when custom parameters are enabled. 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: Use this when personaId is a voiceId generated by Suno Voice. This option is only available with V5 and V5_5 models.
Available options:
style_persona,
voice_persona
Example:

"style_persona"

​
negativeTags
string

Music styles to exclude from generation

Example:

"Relaxing Piano"

​
vocalGender
enum<string>

Preferred vocal gender. Optional; not required if instrumental is set to true. 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.65

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

​
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

Callbacks

POST
{$request.body#/callBackUrl}audioExtend

Body

application/json
​
code
integer

Status code

Example:

200

​
msg
string

Response message

Example:

"All generated successfully"

​
data
object

Response

200

Callback received successfully

Response

Request successful

​
code
enum<integer>

Status Codes

  • ✅ 200 - Request successful
  • ⚠️ 400 - Invalid parameters
  • ⚠️ 401 - Unauthorized access
  • ⚠️ 404 - Invalid request method or path
  • ⚠️ 405 - Rate limit exceeded
  • ⚠️ 413 - Theme or prompt too long
  • ⚠️ 429 - Insufficient credits
  • ⚠️ 430 - Your call frequency is too high. Please try again later.
  • ⚠️ 455 - System maintenance
  • ❌ 500 - Server error
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object