Skip to main content
POST
/
api
/
v1
/
generate
/
upload-cover
Upload And Cover Audio
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/upload-cover \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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,
  "model": "V3_5",
  "negativeTags": "Heavy Metal, Upbeat Drums",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "callBackUrl": "https://api.example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
This API covers an audio track by transforming it into a new style while retaining its core melody. It incorporates Suno’s upload capability, enabling users to upload an audio file for processing. The expected result is a refreshed audio track with a new style, keeping the original melody intact.

​
Upload Requirements

  • File Duration: Maximum 2 minutes
  • Upload URL: Required for all requests regardless of mode
  • File Format: Standard audio formats supported

​
Processing Modes

​
Custom Mode (customMode: true)

  • Required fields: style, title, and prompt (if not instrumental)
  • Gives you full control over the transformation style
  • Prompt becomes exact lyrics if instrumental is false

​
Non-Custom Mode (customMode: false)

  • Required fields: Only prompt
  • Automatically generates style and lyrics based on your prompt
  • Simpler workflow for quick transformations

​
Audio Transformation Process

  1. Upload: Provide the audio file URL (max 2 minutes)
  2. Style Definition: Specify how you want it transformed
  3. Processing: AI analyzes and recreates with new style
  4. Result: New audio maintaining original melody structure

​
Key Features

  • Melody Preservation: Core melody remains intact
  • Style Flexibility: Transform into any musical genre
  • Quality Retention: Professional audio output
  • Fast Processing: Results available via callback or polling
Perfect for reimagining existing tracks in different musical styles while preserving their essential character.

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
​
uploadUrl
string<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 2 minutes in length.

Example:

"https://storage.example.com/upload"

​
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 model version to use for audio generation. Choose between: V3_5, V4, V4_5, or V4_5PLUS. Note: Ensure correct formatting (e.g., use V3_5 or V4, not V3.5 or other variations).

Available options:
V3_5,
V4,
V4_5,
V4_5PLUS
Example:

"V3_5"

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

"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. Max length: 3000 characters. 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: 400 characters.

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. Max length: 200 characters. 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). Max length: 80 characters. In Non-custom Mode (customMode: false): Leave empty.

Example:

"Peaceful Piano Meditation"

​
negativeTags
string

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

Example:

"Heavy Metal, Upbeat Drums"

​
vocalGender
enum<string>

Preferred vocal gender for generated vocals. Optional.

Available options:
m,
f
Example:

"m"

​
styleWeight
number

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

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
weirdnessConstraint
number

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

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
audioWeight
number

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

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

Response

Request successful

​
code
enum<integer>

Status code. 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