Sign in

v1

latestOpenAPI 3.0.02026-07-26355125.0 KB

Generate Music

post/api/v1/generate

Request body

promptstring

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, V4_5ALL, V5 & V5_5: 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). Maximum 500 characters.
    Example: "A short relaxing piano tune"
stylestring

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, V4_5ALL, V5 and V5_5 models: Max length: 1000 characters.
      Example: "Classical"
  • In Non-custom Mode (customMode: false): Leave empty.
titlestring

The title of the generated music track.

  • Required in Custom Mode (customMode: true). Character limits by model:
    • V4 & V4_5ALL: Maximum 80 characters
    • V4_5, V4_5PLUS, V5 & V5_5: Maximum 100 characters
      Example: "Peaceful Piano Meditation"
  • In Non-custom Mode (customMode: false): Leave empty.
customModeboolean 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.
instrumentalboolean 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.
personaIdstring

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.
personaModel'style_persona' | 'voice_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.
model'V4' | 'V4_5' | 'V4_5PLUS' | 'V4_5ALL' | 'V5' | 'V5_5' required

The model version to use for audio generation.

  • Available options:
    • V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste.
    • V5: Superior musical expression, faster generation.
    • V4_5PLUS: V4.5+ is richer sound, new ways to create, max 8 min.
    • V4_5ALL: V4.5-all is better song structure, max 8 min.
    • V4_5: Superior genre blending with smarter prompts and faster output, up to 8 minutes.
    • V4: Best audio quality with refined song structure, up to 4 minutes.
durationnumber

Audio duration in seconds. Optional. Only supported when model is V5_5 and customMode is true. Range: 10–360 seconds. Must be an integer.

negativeTagsstring

Music styles or traits to exclude from the generated audio.

  • Optional. Use to avoid specific styles.
    Example: "Heavy Metal, Upbeat Drums"
vocalGender'm' | 'f'

Preferred vocal gender for generated vocals. Optional.

styleWeightnumber

Weight of the provided style guidance. Range 0.00–1.00.

weirdnessConstraintnumber

Constraint on creative deviation/novelty. Range 0.00–1.00.

audioWeightnumber

Weight of the input audio influence (where applicable). Range 0.00–1.00.

callBackUrlstring uri required

The URL to receive task completion notifications when music generation is complete.

  • For detailed callback format and implementation guide, see Music Generation Callbacks
  • Alternatively, you can use the get music generation details endpoint to poll task status

Example request

{
  "prompt": "A calm and relaxing piano track with soft melodies",
  "style": "Classical",
  "title": "Peaceful Piano Meditation",
  "customMode": true,
  "instrumental": true,
  "personaId": "persona_123",
  "personaModel": "style_persona",
  "model": "V4_5ALL",
  "duration": 60,
  "negativeTags": "Heavy Metal, Upbeat Drums",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "callBackUrl": "https://api.example.com/callback"
}

Response

Request successful

code200 | 400 | 401 | 404 | 405 | 413 | 429 | 430 | 455 | 500

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
msgstring

Error message when code != 200

Example response

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