Skip to main content
POST
/
api
/
v1
/
generate
{
  "customMode": false,
  "instrumental": false,
  "prompt": "A chill lo-fi beat with soft vocals",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

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

​
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

  • In Custom Mode (customMode: true):
    • If instrumental: true: style and title are required
    • If instrumental: false: style, prompt, and title are required
    • Character limits vary by model:
      • V4: prompt 3000 characters, style 200 characters
      • V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL: prompt 5000 characters, style 1000 characters (V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same limits as V5)
    • title length limit: 80 characters (all models)
  • In Non-custom Mode (customMode: false):
    • Only prompt is required regardless of instrumental setting
    • prompt length limit: 500 characters
    • Other parameters should be left empty

​
Optional parameters

The following fields are optional controls available for this endpoint:
  • 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)
  • personaId (string): Persona ID or Suno Voice voiceId to apply in Custom Mode. 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.
{
  "customMode": false,
  "instrumental": false,
  "prompt": "A chill lo-fi beat with soft vocals",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

​
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:

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

Enables Custom Mode for advanced audio generation settings.

  • Set to true to use Custom Mode (requires style and title; prompt required if instrumental is false). The prompt will be strictly used as lyrics if instrumental is false.
  • Set to false for Non-custom Mode (only prompt is required). Lyrics will be auto-generated based on the prompt.
Example:

true

​
instrumental
boolean
required

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

  • In Custom Mode (customMode: true):
    • If true: Only style and title are required.
    • If false: style, title, and prompt are required (with prompt used as the exact lyrics).
  • In Non-custom Mode (customMode: false): No impact on required fields (prompt only). Lyrics are auto-generated if instrumental is false.
Example:

true

​
model
enum<string>
required

The AI model version to use for generation.

  • Required for all requests.
  • Available options:
    • V5: Superior musical expression, faster generation.
    • V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. Same custom-mode prompt and style character limits as V5 (5000 / 1000).
    • V4_5PLUS: V4.5+ is richer sound, new waysto create, max 8 min.
    • V4_5: V4.5 is smarter prompts, fastergenerations, max 8 min.
    • V4: V4 is improved vocal quality,max 4 min.
    • V4_5ALL: V4.5-all is better song structure,max 8 min.
Available options:
V4_5ALL,
V4,
V4_5,
V4_5PLUS,
V5,
V5_5
Example:

"V4_5ALL"

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

  • In Custom Mode (customMode: true): Required if instrumental is false. The prompt will be strictly used as the lyrics and sung in the generated track. Character limits by model:
    • V4: Maximum 3000 characters
    • V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL: Maximum 5000 characters
      Example: "A calm and relaxing piano track with soft melodies"
  • In Non-custom Mode (customMode: false): Always required. The prompt serves as the core idea, and lyrics will be automatically generated based on it (not strictly matching the input). Max length: 500 characters.
    Example: "A short relaxing piano tune"
Example:

"A calm and relaxing piano track with soft melodies"

​
style
string

The music style or genre for the audio.

  • Required in Custom Mode (customMode: true). Examples: "Jazz", "Classical", "Electronic".
    • For V4 model: Max length: 200 characters.
    • For V4_5, V4_5PLUS, V5, V5_5 and V4_5ALL models: Max length: 1000 characters.
      Example: "Classical"
  • In Non-custom Mode (customMode: false): Leave empty.
Example:

"Classical"

​
title
string

The title of the generated music track.

  • Required in Custom Mode (customMode: true). Character limits by model:
    • V4 and V4_5ALL: Max length: 80 characters
    • V4_5, V4_5PLUS, V5 & V5_5: Max length: 100 characters
      Example: "Peaceful Piano Meditation"
  • In Non-custom Mode (customMode: false): Leave empty.
Example:

"Peaceful Piano Meditation"

​
personaId
string

Only available when custom parameters are enabled. 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: Use this when personaId is a voiceId generated by Suno Voice. This option is only available with V5 and V5_5 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

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