v1

latestOpenAPI 3.0.02026-07-26355125.0 KB

Upload And Cover Audio

post/api/v1/generate/upload-cover

Request body

uploadUrlstring uri required

The URL for uploading audio files, required regardless of whether customMode and instrumental are true or false. Ensure the uploaded audio does not exceed 8 minutes in length.

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". Character limits by model:
- V4: Maximum 200 characters
- V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 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.

The model version to use for audio generation.

Choose between: V4, V4_5, V4_5PLUS, V4_5ALL, V5, or V5_5. Note: Ensure correct formatting (e.g., use "V4" or "V4_5ALL", not "V4.5" or other variations).

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.

durationinteger

Optional duration in seconds. Only effective when customMode is true and model is V5_5.

callBackUrlstring uri required

The URL to receive task completion notifications when audio covering is complete.

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

Example request

{
  "uploadUrl": "https://storage.example.com/upload",
  "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",
  "negativeTags": "Heavy Metal, Upbeat Drums",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "duration": 20,
  "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"
  }
}