{
  "instrumental": false,
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

POST

api

generate

upload-extend

{
  "instrumental": false,
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

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 runs in custom mode. Simple mode is not available. A source audio (uploadUrl) is enough to generate; lyrics (or prompt), title, and style are optional.
Required: uploadUrl, model, callBackUrl
instrumental (boolean, optional) determines whether to generate instrumental music and defaults to false.
prompt is lyrics. Optional. If lyrics is also provided, lyrics takes priority and prompt is not used as lyrics.
Character limits (based on model):
- V4 model (Deprecated): prompt max 3000 characters, style max 200 characters
- V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL models (Deprecated): prompt max 5000 characters, style max 1000 characters
- V6, V6_WILD & V6_MINI models: lyrics/prompt max 5000 characters, style max 1000 characters, title max 100 characters
model (string, required): V6, V6_WILD, V6_MINI. Deprecated: V4_5ALL, V4, V4_5, V4_5PLUS, V5, V5_5.
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 source audio file; ensure uploaded audio does not exceed 8 minutes.

Optional parameters

The following fields are optional controls available for this endpoint:

lyrics (string): Lyrics content. Optional. V6 series maximum 5000 characters. Takes priority over prompt as lyrics.
prompt (string): Lyrics content. Optional. Used as lyrics when lyrics is not provided. V6 series maximum 5000 characters.
style (string): Music style. Optional. V6 series maximum 1000 characters.
title (string): Track title. Optional. Maximum 100 characters.
continueAt (number): Time point in seconds from which to start extending. Greater than 0 and less than the uploaded audio duration.
vocalGender (string): Optional. 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.

{
  "instrumental": false,
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

Developer Notes

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

Authorizations

Authorization

string

header

required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

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 of the source audio file to extend. Required. With a source audio URL, generation can proceed; lyrics (or prompt), title, and style are optional. Ensure the uploaded audio does not exceed 8 minutes in length.

Example:

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

model

enum<string>

default:V6

required

AI model version. Default: V6.

V6: Current standard model and recommended default.
V6_WILD: Current model for more experimental and creative results.
V6_MINI: Current lightweight model.
Deprecated: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, and V4. These values remain listed only for backward compatibility; use a V6-series model for new integrations.

Available options:

V6,

V6_WILD,

V6_MINI,

V5_5,

V5,

V4_5PLUS,

V4_5ALL,

V4_5,

V4

Example:

"V6"

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). Optional. Defaults to false.

Example:

false

prompt

string

Lyrics content. Optional. Used as lyrics when lyrics is not provided. If lyrics is also provided, lyrics takes priority and this field is not used as lyrics.

V4 (Deprecated): Maximum 3000 characters
V4_5, V4_5PLUS, V4_5ALL, V5, V5_5 (Deprecated): Maximum 5000 characters
V6, V6_WILD, V6_MINI: Maximum 5000 characters

Example:

"[Verse] Night city lights shining bright"

lyrics

string

Lyrics for the generated audio. Optional. For V6, V6_MINI, and V6_WILD: maximum 5000 characters. Takes priority over prompt as lyrics. If omitted, prompt is used as lyrics.

Example:

"[Verse] Night city lights shining bright"

style

string

Music style, e.g. Jazz, Classical, or Electronic. Optional. For V6, V6_WILD, and V6_MINI: maximum 1000 characters.

V4 (Deprecated): Maximum 200 characters
V4_5, V4_5PLUS, V4_5ALL, V5, V5_5 (Deprecated): Maximum 1000 characters

Example:

"Classical"

title

string

Music title. Optional. Maximum 100 characters.

Maximum string length: 100

Example:

"Peaceful Piano Extended"

continueAt

number

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

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

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"

negativeTags

string

Music styles to exclude from generation

Example:

"Relaxing Piano"

vocalGender

enum<string>

Preferred vocal gender. Optional. Allowed values: m (male), f (female). Not required when instrumental is true.

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

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

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

Show child attributes

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

Show child attributes

Generate Music

Suno Voice

Generate Lyrics

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

Upload And Extend Audio

Model Versions

Parameter Usage Guide

Optional parameters

Developer Notes

Authorizations

🔑 API Authentication

Get API Key

Usage

Body

Callbacks

Body

Response

Response

Status Codes

​Model Versions

​Parameter Usage Guide

​Optional parameters

​Developer Notes

Authorizations

🔑 API Authentication

Get API Key

Usage

Body

Callbacks

Body

Response

Response

Status Codes

Model Versions

Parameter Usage Guide

Optional parameters

Developer Notes