Skip to main content
POST
Upload And Extend Audio

Parameter Usage Guide

  • instrumental determines whether the audio is instrumental (without lyrics) and defaults to false
  • prompt is optional in all cases; when provided, it is used as a generation prompt
  • When defaultParamFlag is true (Custom Parameters):
    • If instrumental is true: only style, title, and uploadUrl are required; prompt and vocalGender are not required
    • If instrumental is false: style, title, and uploadUrl are required; prompt is optional and used as a generation prompt when provided, and vocalGender is not required
    • prompt length limit by model:
      • V4: Maximum 3000 characters
      • V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 5000 characters
    • style length limit by model:
      • V4: Maximum 200 characters
      • V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 1000 characters
    • title length limit by model:
      • V4 & V4_5ALL: Maximum 80 characters
      • V4_5, V4_5PLUS, V5 & V5_5: Maximum 100 characters
    • 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.
      • Important: When using the V4_5ALL model, the uploaded audio file must not exceed 1 minute in length.
  • When defaultParamFlag is false (Default Parameters):
    • Regardless of instrumental setting, 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

  • 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. V4_5ALL Model Upload Limit: When using the V4_5ALL model, the uploaded audio file must not exceed 1 minute in length.
  4. This feature is ideal for creating longer works by extending existing music
  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

Model version to use, must be consistent with the source audio

Available options:
V4,
V4_5,
V4_5PLUS,
V4_5ALL,
V5,
V5_5
Example:

"V4_5ALL"

callBackUrl
string<uri>
required

The URL to receive task completion notifications when music extension is complete.

  • For detailed callback format and implementation guide, see Upload and Extend Audio Callbacks
  • Alternatively, you can use the get music generation details endpoint 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. Required when defaultParamFlag is true. Character limits by model:

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

"Classical"

title
string

Music title. Required when defaultParamFlag is true. 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; no value is required for this endpoint.

Available options:
m,
f
Example:

"m"

styleWeight
number

Weight of the provided style guidance. Range 0.00–1.00.

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

0.65

weirdnessConstraint
number

Constraint on creative deviation/novelty. Range 0.00–1.00.

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

0.65

audioWeight
number

Weight of the input audio influence (where applicable). Range 0.00–1.00.

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