Skip to main content
POST

​
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. 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 (or prompt), title, and style are optional.
  • Required: uploadUrl or both taskId and audioId, plus model and callBackUrl
  • model (string, required): V6, V6_WILD, V6_MINI. Deprecated: V4_5ALL, V4, V4_5, V4_5PLUS, V5, V5_5.
  • 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 80 characters
  • uploadUrl specifies the source audio file; when using upload mode, ensure the uploaded audio 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 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 80 characters.
  • instrumental (boolean): Whether to generate instrumental music. Defaults to false.
  • 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 (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.

​
Developer Notes

  1. Recommended settings for new users: provide uploadUrl, model, and callBackUrl. lyrics, title, and style are optional.
  2. Generated files will be deleted after 15 days
  3. Pay attention to character limits for lyrics/prompt, style, and title to ensure successful processing
  4. Callback process has three stages: text (text generation complete), first (first track complete), complete (all tracks complete)
  5. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks
  6. The uploadUrl parameter specifies the source audio file; 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

  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 of the source audio file 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"

​
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 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 80 characters.

Maximum string length: 80
Example:

"Peaceful Piano Meditation"

​
instrumental
boolean

Determines if the audio should be instrumental (no lyrics). Optional. Defaults to false.

Example:

true

​
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, up to 2 decimal places.

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

0.65

​
weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range 0–1, up to 2 decimal places.

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, up to 2 decimal places.

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

​
duration
integer

Duration in seconds. Optional. Range 10–360. Only valid when the model is V5_5 (Deprecated), V6, V6_WILD, or V6_MINI.

Required range: 10 <= x <= 360
Example:

20

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

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