Sign in

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

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"
  }
}

Changes