Skip to main content
POST
/
api
/
v1
/
generate
/
upload-extend
Upload And Extend Audio
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/upload-extend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrl": "https://storage.example.com/upload",
  "defaultParamFlag": true,
  "model": "V4_5ALL",
  "callBackUrl": "https://api.example.com/callback",
  "instrumental": true,
  "prompt": "Extend the music with more relaxing notes",
  "style": "Classical",
  "title": "Peaceful Piano Extended",
  "continueAt": 60,
  "personaId": "persona_123",
  "personaModel": "style_persona",
  "negativeTags": "Relaxing Piano",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Parameter Usage Guide

  • When defaultParamFlag is true (Custom Parameters):
    • If instrumental is true: style, title, and uploadUrl are required
    • If instrumental is false: style, prompt, title, and uploadUrl are 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 and prompt are required
    • 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:

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

Enable custom mode for advanced audio generation settings.

  • Set to true to use custom parameter mode (requires style, title, and uploadUrl; if instrumental is false, uploadUrl and prompt are required). If instrumental is false, the prompt will be strictly used as lyrics.
  • Set to false to use non-custom mode (only uploadUrl required). Lyrics will be automatically generated based on the prompt.
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

Determines whether the audio is instrumental (without lyrics).

  • In custom parameter mode (defaultParamFlag: true):
    • If true: only style, title, and uploadUrl are required.
    • If false: style, title, prompt (prompt will be used as exact lyrics), and uploadUrl are required.
  • In non-custom parameter mode (defaultParamFlag: false): does not affect required fields (only uploadUrl needed). If false, lyrics will be automatically generated.
Example:

true

​
prompt
string

Description of how the music should be extended. Required when defaultParamFlag is true. 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, V4_5ALL, V5 & V5_5: 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 for generated vocals. Optional.

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