Appearance
Upload And Cover Audio
POST
/api/v1/generate/upload-cover
This API creates a cover version of 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.
Parameter Usage Guide #
Character Limits
Character limits vary depending on the model version:
Model V5_5 and V5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
Models V4.5PLUS and V4.5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
Model V4.5ALL: style (max 1000 chars), title (max 80 chars), prompt (max 5000 chars)
Model V4: style (max 200 chars), title (max 80 chars), prompt (max 3000 chars)
When customMode is true (Custom Mode):
If instrumental is true: style, title, and uploadUrl are required.
If instrumental is false: style, prompt, title, and uploadUrl are required.
Character limits vary by model version (see note above).
uploadUrl is used to specify the upload location of the audio file; ensure the uploaded audio does not exceed 8 minutes in length.
When customMode is false (Non-custom Mode):
Only prompt and uploadUrl are required, regardless of the instrumental setting.
prompt length limit: 500 characters.
Other parameters should be left empty.
Developer Notes #
Quick Start for New Users: Set customMode to false, instrumental to false, and provide only prompt and uploadUrl. This is the simplest configuration to quickly test the API and experience the results.
Generated files will be deleted after 15 days.
Ensure all required parameters are provided based on the customMode and instrumental settings to avoid errors.
Pay attention to character limits for prompt, style, and title to ensure successful processing.
Callback Process Stages: The callback process has three stages: text (text generation complete), first (first track complete), and complete (all tracks complete).
Active Status Check: You can use the Get Music Generation Details endpoint to actively check the task status instead of waiting for callbacks.
The uploadUrl parameter is used to specify the upload location of the audio file; please provide a valid URL.
Optional Parameters #
vocalGender (string): Vocal gender preference. Use m for male, f for female.
styleWeight (number): Strength of adherence to style. Range 0-1, up to 2 decimal places. Example: 0.65.
weirdnessConstraint (number): Controls creative deviation. Range 0-1, up to 2 decimal places. Example: 0.65.
audioWeight (number): Balance weight for audio features. Range 0-1, up to 2 decimal places. Example: 0.65.
personaId (string): Persona ID to apply to the generated music. Only available when Custom Mode is enabled (i.e., customMode is true). To create one, use Generate Persona.
Callbacks
audioGenerated
POST
Request
Authorization
Bearer Token
Provide your bearer token in the Authorization header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params application/jsonRequired
Generate Code
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 8 minutes in length.
Example: https://storage.example.com/upload
prompt
string
required
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:
V5_5 & V5: Maximum 5000 characters
V4_5PLUS & V4_5: Maximum 5000 characters
V4_5ALL: Maximum 5000 characters
V4: Maximum 3000 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
optional
The music style or genre for the audio.
Required in Custom Mode (customMode: true). Examples: "Jazz", "Classical", "Electronic". Character limits by model:
V5_5 & V5: Maximum 1000 characters
V4_5PLUS & V4_5: Maximum 1000 characters
V4_5ALL: Maximum 1000 characters
V4: Maximum 200 characters
Example: "Classical"
In Non-custom Mode (customMode: false): Leave empty.
Example: Classical
title
string
optional
The title of the generated music track.
Required in Custom Mode (customMode: true). Character limits by model:
V5_5 & V5: Maximum 100 characters
V4_5PLUS & V4_5: Maximum 100 characters
V4_5ALL: Maximum 80 characters
V4: Maximum 80 characters
Example: "Peaceful Piano Meditation"
In Non-custom Mode (customMode: false): Leave empty.
Example: Peaceful Piano Meditation
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_5：Custom Models Tailored to Your Unique Taste.
V5: Superior musical expression, faster generation.
V4_5PLUS: V4.5+ delivers richer sound, new ways to create, max 8 min.
V4_5: V4.5 enables smarter prompts, faster generations, max 8 min.
V4_5ALL: V4.5ALL enables smarter prompts, faster generations, max 8 min.
V4: V4 improves vocal quality, max 4 min.
Allowed values: V4V4_5V4_5PLUSV4_5ALLV5V5_5
Example: V4
negativeTags
string
optional
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
callBackUrl
string<uri>
required
The URL to receive audio covering task completion updates. Required for all audio covering requests.
System will POST task status and results to this URL when audio covering completes
Callback includes generated covered audio files with new style while preserving original melody
Your callback endpoint should accept POST requests with JSON payload containing covered track results and audio URLs
For detailed callback format and implementation guide, see Audio Covering Callbacks
Alternatively, use the Get Music Details endpoint to poll task status
To ensure callback security, see Webhook Verification Guide for signature verification implementation
Example: https://api.example.com/callback
vocalGender
enum<string>
optional
Vocal gender preference for the singing voice. Optional. Use 'm' for male and 'f' for female. Note: This parameter is only effective when customMode is true. Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions.
Allowed values: mf
Example: m
styleWeight
number
optional
Strength of adherence to the specified style. Optional. Range 0-1, up to 2 decimal places.
= 0<= 1
Example: 0.65
Multiple of: 0.01
weirdnessConstraint
number
optional
Controls experimental/creative deviation. Optional. Range 0-1, up to 2 decimal places.
= 0<= 1
Example: 0.65
Multiple of: 0.01
audioWeight
number
optional
Balance weight for audio features vs. other factors. Optional. Range 0-1, up to 2 decimal places.
= 0<= 1
Example: 0.65
Multiple of: 0.01
personaId
string
optional
Only available when Custom Mode (customMode: true) is enabled. Persona ID or Voice ID to apply to the generated music. Optional. Use this to apply a specific persona style to your music generation.To generate a persona ID, use the Generate Persona endpoint to create a personalized music Persona based on generated music.To generate a Voice ID, use the Generate Voice endpoint
Example: persona_123
personaModel
enum<string>
optional
The persona model is only available for models version 5 and 5.5.
Allowed values: voice_personastyle_persona
Examples
Responses
🟢200
application/json
Request successful
Bodyapplication/json
Generate Code
code
enum<integer>
optional
Response status code
200: Success - Request has been processed successfully
401: Unauthorized - Authentication credentials are missing or invalid
402: Insufficient Credits - Account does not have enough credits to perform the operation
404: Not Found - The requested resource or endpoint does not exist
409: Conflict - WAV record already exists
422: Validation Error - The request parameters failed validation checks
429: Rate Limited - Request limit has been exceeded for this resource
451: Unauthorized - Failed to fetch the image. Kindly verify any access limits set by you or your service provider.
455: Service Unavailable - System is currently undergoing maintenance
500: Server Error - An unexpected error occurred while processing the request
Allowed values: 200401402404409422429451455500
msg
string
optional
Error message when code != 200
Example: success
data
object
optional
taskId
string
optional
Task ID for tracking task status
Example: 5c79****be8e
🔴500Error
Request Request Example
Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
cURLcURL-WindowsHttpiewgetPowerShell
curl --location 'https://api.kie.ai/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",
"customMode": true,
"instrumental": true,
"model": "V4",
"callBackUrl": "https://api.example.com/callback",
"style": "Classical",
"title": "Peaceful Piano Meditation",
"negativeTags": "Heavy Metal, Upbeat Drums",
"vocalGender": "m",
"styleWeight": 0.65,
"weirdnessConstraint": 0.65,
"audioWeight": 0.65,
"personaId": "persona_123",
"personaModel": "style_persona"
}'Response Response Example
200 - Example 1
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}