{
  "instrumental": false,
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

POST

api

generate

upload-extend

{
  "instrumental": false,
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

{
  "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 uses custom parameters. Simple mode is not available.
Source audio (uploadUrl) is enough to generate. lyrics, prompt, style, and title are optional.
instrumental (boolean, optional) determines whether to generate instrumental music and defaults to false.
- If instrumental is true: generate instrumental music. prompt, lyrics, and vocalGender do not need to be provided.
- If instrumental is false: use lyrics as the lyrics when provided; otherwise use prompt. Both are optional. vocalGender is optional.
prompt is optional and is treated as lyrics. When lyrics is also provided, lyrics takes priority and prompt is not used as lyrics.
lyrics is optional. It takes priority over prompt as the lyrics. If lyrics is omitted, prompt is used as the lyrics.
Character limits (based on model):
- V4 model (Deprecated): prompt max 3000 characters, style max 200 characters, title max 80 characters
- V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL models (Deprecated): prompt max 5000 characters, style max 1000 characters; title max 80 characters for V4_5ALL, otherwise max 100 characters
- V6, V6_WILD & V6_MINI models: prompt and lyrics 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). Required.
uploadUrl: source audio URL. Required. Ensure uploaded audio does not exceed 8 minutes.

Optional parameters

The following fields are optional controls available for this endpoint:

lyrics (string): Lyrics for the extension. Optional. Takes priority over prompt. If omitted, prompt is used as the lyrics. For V6, V6_WILD, and V6_MINI: maximum 5000 characters.
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)
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. Use style_persona for Generate Persona IDs, or voice_persona for Suno Voice IDs.

{
  "instrumental": false,
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electropop",
  "title": "Shimmer (Extended)",
  "continueAt": 45,
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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 prompt, lyrics, style, and title to ensure successful processing
uploadUrl is the source audio URL and is enough to generate; 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

URL of the source audio to extend. Required. Providing this source audio is enough to generate; lyrics, prompt, style, and title are optional. Ensure the uploaded audio does not exceed 8 minutes in length.

Example:

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

continueAt

number

required

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

Required.
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

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). This endpoint always uses custom parameters. Optional. Defaults to false.

If true: generate instrumental music. prompt, lyrics, and vocalGender do not need to be provided.
If false: use lyrics as the lyrics when provided; otherwise use prompt. Both are optional. vocalGender does not need to be provided.
style and title are optional in either case.

Example:

false

prompt

string

Lyrics for the extension. Optional. When provided, it is used as lyrics. If lyrics is also provided, lyrics takes priority and prompt is not used as lyrics. Character limits by model:

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] City hums under neon rain"

lyrics

string

Lyrics for the extension. Optional. Takes priority over prompt as the lyrics. If lyrics is omitted, prompt is used as the lyrics.

V6, V6_WILD & V6_MINI: Maximum 5000 characters

Example:

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

style

string

Music style, e.g. Jazz, Classical, or Electronic. Optional. Source audio (uploadUrl) alone is enough to generate. Character limits by model:

V4 (Deprecated): Maximum 200 characters
V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL (Deprecated): Maximum 1000 characters
V6, V6_WILD & V6_MINI: Maximum 1000 characters

Example:

"Classical"

title

string

Music title. Optional. Character limits by model:

V4 & V4_5ALL (Deprecated): Maximum 80 characters
V4_5, V4_5PLUS, V5 & V5_5 (Deprecated): Maximum 100 characters
V6, V6_WILD & V6_MINI: Maximum 100 characters

Example:

"Peaceful Piano Extended"

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

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

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

Lyrics Generation

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