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.

​
Usage Guide

  • This endpoint creates music based on your text prompt
  • Multiple variations will be generated for each request
  • You can control detail level with custom mode and instrumental settings

​
Parameter Details

  • Always required: customMode, instrumental, model
  • In Custom Mode (customMode: true):
    • title is optional, maximum 80 characters. Only available in this mode; not supported when customMode is false
    • prompt is optional; when provided, it is used strictly as lyrics and sung in the generated track. If lyrics is also provided, lyrics takes priority
    • At least one of style, lyrics, or negativeTags must be provided; generation is rejected if all are empty
    • If instrumental: true: generate instrumental music (no vocals)
    • If instrumental: false: use lyrics as lyrics (fall back to prompt if lyrics is not provided)
    • negativeTags, vocalGender, and duration are available only in this mode. Do not pass them when customMode is false
    • Optional: duration (10–360 seconds), negativeTags (V6 max 1000 characters), vocalGender (m / f), styleWeight, weirdnessConstraint, audioWeight, variety, personaId, personaModel
    • Character limits by model:
      • V4 (Deprecated): prompt 3000 characters, style 200 characters
      • V4_5, V4_5PLUS, V4_5ALL, V5, V5_5 (Deprecated): prompt 5000 characters, style 1000 characters
      • V6, V6_MINI, V6_WILD: style 1000 characters; lyrics 5000 characters; negativeTags 1000 characters
    • title length limit: 80 characters (all models)
  • In Non-custom Mode (customMode: false):
    • prompt is optional; it serves as the core idea, and lyrics are generated automatically (not a strict match), maximum 3000 characters
    • lyrics can be used as a lyrics attachment together with prompt
    • At least one of imageUrls, videoUrls, audioUrls, style, or lyrics must be provided; generation is rejected if all are empty
    • imageUrls, videoUrls, and audioUrls are only valid in this mode
    • Do not pass parameters that are only available in custom mode: title, negativeTags, duration, vocalGender, styleWeight, weirdnessConstraint, audioWeight, variety
    • Total attachments must not exceed 10: style + lyrics + imageUrls + videoUrls + audioUrls

​
Optional Parameters

The following fields are optional controls available for this endpoint:
  • prompt (string): Description of the desired audio content. Optional. Used as lyrics in custom mode; used as the core idea in non-custom mode (maximum 3000 characters).
  • lyrics (string): Lyrics content. Optional. V6 series maximum 5000 characters. In custom mode, takes priority over prompt as lyrics; in non-custom mode, can be used as a lyrics attachment together with prompt.
  • imageUrls (array): Image references. Only effective when customMode is false. Up to 5 images, each no more than 10 MB. Supported formats: jpeg, png, webp, bmp.
  • videoUrls (array): Video references. Only effective when customMode is false. Up to 1 file, each no more than 100 MB, duration no more than 241 seconds. Supported formats: mp4, mov, webm.
  • audioUrls (array): Audio references. Only effective when customMode is false. Duration must be between 6 seconds and 30 minutes; each file no more than 500 MB.
  • style (string): Music style specification. See character limits in Parameter Details above.
  • title (string): Track title. Optional. Only available when customMode is true. Maximum 80 characters. Displayed in player interfaces and filenames.
  • negativeTags (string): Music styles or traits to exclude from the generated audio. Only available when customMode is true. For V6, V6_MINI, and V6_WILD: maximum 1000 characters.
  • vocalGender (string): Vocal gender preference. m for male, f for female. Only available when customMode is true. In practice, this only increases probability and cannot guarantee the instruction is followed.
  • styleWeight (number): Strength of adherence to the specified style. Range 0–1, up to 2 decimal places. Only effective when customMode is true.
  • weirdnessConstraint (number): Creative/experimental deviation. Range 0–1, up to 2 decimal places. Only effective when customMode is true.
  • audioWeight (number): Relative weight of audio features. Range 0–1, up to 2 decimal places. Only effective when customMode is true. Not supported when there are no vocals.
  • variety (number): Diversity of generated results. Integer from 0–4, default 1. Only effective when customMode is true. 0 off (exact style), 1 normal (default, balanced), 2 high (distinct styles), 3 extra (bold exploration), 4 max (maximum variation).
  • personaId (string): Persona ID or Voice ID. Optional. To generate a Persona ID, see Generate Persona.
  • personaModel (string): Persona model, style_persona or voice_persona. Only available for V5 (Discontinued), V5_5 (Discontinued), V6, V6_MINI, and V6_WILD.
  • duration (number): Audio duration in seconds. Range 10–360, default 20. Only available when customMode is true, and only valid when the model is V5_5, V6, V6_MINI, or V6_WILD.

​
Developer Notes

  • Recommendation for new users: Start with customMode: false for simpler usage
  • Generated files are retained for 14 days
  • Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)

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
​
customMode
boolean
required

Determines whether advanced parameter customization is enabled.

  • If true: Allows detailed control
  • If false: Simplified mode
Example:

true

​
instrumental
boolean
required

Determines whether the audio should be instrumental (no lyrics).

  • In Custom Mode (customMode: true):
    • If true: generate instrumental music (no vocals)
    • If false: use lyrics as lyrics (fall back to prompt if lyrics is not provided)
  • In Non-custom Mode (customMode: false):
    • If true: generate instrumental music (no vocals)
    • If false: lyrics can be used as a lyrics attachment together with the audio description in prompt
Example:

true

​
model
enum<string>
default:V6
required

The AI model version to use for generation. Required for all requests. Default: V6. Available options:

  • V6_WILD: Pushes creative boundaries for bolder, more distinctive musical expression.
  • V6_MINI: Lightweight and fast, balancing quality and speed for effortless creation.
  • V6: Greater musical expression with more natural vocals and richer details. Recommended default.
  • V5_5 (Discontinued): Custom models tailored to your unique taste.
  • V5 (Discontinued): Superior musical expression, faster generation.
  • V4_5PLUS (Discontinued): V4.5+ delivers richer sound, new ways to create, max 8 min.
  • V4_5 (Discontinued): V4.5 enables smarter prompts, faster generations, max 8 min.
  • V4_5ALL (Discontinued): V4.5ALL enables smarter prompts, faster generations, max 8 min.
  • V4 (Discontinued): V4 improves vocal quality, max 4 min. Discontinued 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 music generation 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 Music Generation Callbacks
  • Alternatively, you can use the Get Music Generation Details interface to poll task status
Example:

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

​
prompt
string

A description of the desired audio content. Optional.

  • Custom mode (customMode=true): When provided, the prompt is used strictly as lyrics and sung in the generated track. If lyrics is also provided, lyrics takes priority. Character limits by model:
    • V4 (Discontinued): Maximum 3000 characters
    • V4_5, V4_5PLUS, V4_5ALL, V5_5, V5 (Discontinued): Maximum 5000 characters
  • Non-custom mode (customMode=false): When provided, the prompt serves as the core idea. Lyrics are generated automatically based on it and do not strictly match the input. Maximum 3000 characters. prompt is not required. In non-custom mode, provide at least one of imageUrls, videoUrls, audioUrls, style, or lyrics. In custom mode, provide at least one of style, lyrics, or negativeTags. Generation is rejected if all related inputs are empty.
Example:

"A calm and relaxing piano track with soft melodies"

​
lyrics
string

Lyrics for the generated audio. Optional.

  • V6, V6_MINI, V6_WILD: Maximum 5000 characters.
  • When customMode=true, lyrics is used as lyrics first; if lyrics is not provided, prompt is used as lyrics.
  • When customMode=false, lyrics is used as a lyrics attachment and can be used together with the audio description in prompt.
Example:

"[Verse] Night city lights shining bright"

​
imageUrls
string[]

Image references. Only effective when customMode=false.

  • Optional
  • Up to 5 images; each image must not exceed 10 MB
  • Supported formats: jpeg, png, webp, and bmp
  • In non-custom mode, total attachments must not exceed 10: style + lyrics + imageUrls + videoUrls + audioUrls
Maximum array length: 5
Example:
​
videoUrls
string[]

Video references. Only effective when customMode=false.

  • Optional
  • Up to 1 video file; each file must not exceed 100 MB, duration must not exceed 241 seconds, with no minimum duration
  • Supported formats: mp4, mov, and webm
Maximum array length: 1
Example:
​
audioUrls
string[]

Audio references. Only effective when customMode=false.

  • Optional
  • Audio duration must be between 6 seconds and 30 minutes; each audio file must not exceed 500 MB
Example:
​
style
string

Music style specification for the generated audio.

  • Character limits by model:
    • V4 (Discontinued): Maximum 200 characters
    • V4_5 and V4_5PLUS (Discontinued): Maximum 1000 characters
    • V4_5ALL (Discontinued): Maximum 1000 characters
    • V5_5 and V5 (Discontinued): Maximum 1000 characters
    • V6, V6_MINI, and V6_WILD: Maximum 1000 characters
  • Common examples: Jazz, Classical, Electronic, Pop, Rock, Hip-hop, etc.
  • In custom mode, provide at least one of style, lyrics, or negativeTags. In non-custom mode, provide at least one of imageUrls, videoUrls, audioUrls, style, or lyrics.
Example:

"Classical"

​
title
string

Title for the generated music track. Optional.

  • Only available when customMode is true. Not supported when customMode is false.
  • Maximum 80 characters.
  • Displayed in player interfaces and filenames.
Maximum string length: 80
Example:

"Peaceful Piano Meditation"

​
negativeTags
string

Music styles or traits to exclude from the generated audio. Optional.

  • Only available when customMode is true. Do not pass this field when customMode is false.
  • For V6, V6_MINI, and V6_WILD: maximum 1000 characters.
  • In custom mode, provide at least one of style, lyrics, or negativeTags.
Maximum string length: 1000
Example:

"Heavy Metal, Upbeat Drums"

​
vocalGender
enum<string>

Vocal gender preference. Optional.

  • Only available when customMode is true. Do not pass this field when customMode is false.
  • Use m for male and f for female.
  • In practice, this only increases probability and cannot guarantee male/female voice instructions are followed.
Available options:
m,
f
Example:

"m"

​
styleWeight
number

Only available when Custom Mode (customMode: true) is enabled. Strength of adherence to the specified style. 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

Only available when Custom Mode (customMode: true) is enabled. Controls experimental/creative deviation. 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

Only available when Custom Mode (customMode: true) is enabled. Relative weight of audio features. Optional. Range 0–1, up to 2 decimal places.

  • audioWeight is not supported when there are no vocals
Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
variety
number
default:1

Only available when Custom Mode (customMode: true) is enabled. Controls the diversity and stylistic variation of generated results. Optional. Range 0–4, integer, 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

​
personaId
string

Persona ID or Voice ID to apply to the generated music. Optional. Use this to apply a specific persona style to your music generation.

To generate a Persona ID, use the Generate Persona endpoint to create a personalized music Persona based on generated music.

To generate a Voice ID, use the Generate Voice endpoint. When using a Voice-generated ID, you must set personaModel: voice_persona.

Example:

"persona_123"

​
personaModel
enum<string>
default:style_persona

Persona model. Optional style_persona or voice_persona. Only available for V5 (Discontinued), V5_5 (Discontinued), V6, V6_MINI, and V6_WILD.

  • 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.
Available options:
style_persona,
voice_persona
Example:

"style_persona"

​
duration
number
default:20

Audio duration in seconds. Optional.

  • Only available when customMode is true. Do not pass this field when customMode is false.
  • Range: 10–360 seconds. Default: 20.
  • Only valid when the model is V5_5 (Discontinued), V6, V6_MINI, or V6_WILD.
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