{
  "instrumental": false,
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

POST

api

generate

upload-cover

{
  "instrumental": false,
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "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.
Choose one source audio input: provide uploadUrl, or provide both taskId and audioId to use an existing generated track. These inputs are mutually exclusive.
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 and lyrics do not need to be provided.
- If instrumental is false: use lyrics as the lyrics when provided; otherwise use prompt. Both are 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 80 characters
model (string, required): V6, V6_WILD, V6_MINI. Deprecated: V4_5ALL, V4, V4_5, V4_5PLUS, V5, V5_5.
uploadUrl is the source audio URL. When using an uploaded audio file, ensure it does not exceed 8 minutes in length.
taskId is the existing music generation task ID and audioId is the existing music ID. Provide both when covering an existing generated track.

Optional parameters

The following fields are optional controls available for this endpoint:

lyrics (string): Lyrics for the cover. 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): Preferred vocal gender. 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": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

{
  "instrumental": false,
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "model": "V6",
  "callBackUrl": "https://example.com/callback"
}

Developer Notes

Recommended settings for new users: Set instrumental to false and provide only uploadUrl. This is the simplest configuration to quickly test the API and experience the results.
Generated files will be deleted after 15 days
This endpoint always uses custom parameters. Provide either uploadUrl or both taskId and audioId; do not provide both source modes together.
Pay attention to character limits for prompt, lyrics, style, and title to ensure successful processing
Callback process has three stages: text (text generation complete), first (first track complete), complete (all tracks complete)
You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks
The uploadUrl parameter specifies the source audio URL; please provide a valid URL when using upload mode.

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

Cover using uploaded audio
Cover using existing audio

uploadUrl

string<uri>

required

URL of the source audio to cover. Required when using uploaded audio. Cannot be used together with taskId and audioId.

Upload Audio Duration Limits: Maximum upload duration is 8 minutes

Example:

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

instrumental

boolean

required

Determines if the audio should be instrumental (no lyrics). This endpoint always uses custom parameters; simple mode is not available.

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

Example:

true

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 cover 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 Cover Audio Callbacks
Alternatively, you can use the Get Music Generation Details interface to poll task status

Example:

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

prompt

string

Lyrics for the cover. Optional. When provided, it is used strictly as lyrics and sung in the generated track. 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, V5, V5_5 & V4_5ALL (Deprecated): Maximum 5000 characters
V6, V6_WILD & V6_MINI: Maximum 5000 characters

Example:

"[Verse] City hums under neon rain"

lyrics

string

Lyrics for the cover. 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

The music style or genre, e.g. "Jazz", "Classical", "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

The title of the generated music track. 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 80 characters

Example:

"Peaceful Piano Meditation"

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 or traits to exclude from the generated audio.

Optional. Use to avoid specific styles.
Example: "Heavy Metal, Upbeat Drums"

Example:

"Heavy Metal, Upbeat Drums"

vocalGender

enum<string>

Preferred vocal gender. Optional. 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

duration

number

Duration in seconds. Optional. Only effective when model is V5_5 (Deprecated), V6, V6_WILD, or V6_MINI.

Required range: 10 <= x <= 360

Example:

20

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}audioGenerated

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