Upload And Cover Audio
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.
Parameter Usage Guide
Character limits vary depending on the model version:
- For model V5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
- For models V4_5PLUS and V4_5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
- For model V4_5ALL: style (max 1000 chars), title (max 80 chars), prompt (max 5000 chars)
- For 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 instrumental setting
- prompt length limit: 500 characters
- Other parameters should be left empty
Developer Notes
- Recommended settings for new users: Set customMode to false, instrumental to false, and only provide 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 customMode and instrumental settings to avoid errors
- Pay attention to character limits for prompt, style, and title to ensure successful processing
- Callback process has three stages: text (text generation complete), first (first track complete), complete (all tracks complete)
- You can use the Get Music Generation Details endpoint to actively check 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. Usemfor male,ffor female.styleWeight(number): Strength of adherence to style. Range 0–1, up to 2 decimals. Example:0.65.weirdnessConstraint(number): Controls creative deviation. Range 0–1, up to 2 decimals. Example:0.65.audioWeight(number): Balance weight for audio features. Range 0–1, up to 2 decimals. Example:0.65.personaId(string): Persona ID to apply to the generated music. Only available when Custom Mode is enabled. To create one, use Generate Persona.
Rate limits and quotas are enforced by Apikley and may differ from upstream providers.
OpenAPI
suno-api/suno-api.json post /api/v1/generate/upload-cover
openapi: 3.0.0
info:
title: Suno API
description: Apikley Suno API Documentation
version: 1.0.0
contact:
name: Technical Support
email: support@apikley.ru
servers:
- url: https://api.apikley.ru
description: API Server
security:
- BearerAuth: []
paths:
/api/v1/generate/upload-cover:
post:
summary: Upload And Cover Audio
description: >-
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.
### Parameter Usage Guide
- 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:**
- **V5**: prompt (max 5000 chars), style (max 1000 chars), title (max 100 chars)
- **V4_5PLUS & V4_5**: prompt (max 5000 chars), style (max 1000 chars), title (max 100 chars)
- **V4_5ALL**: prompt (max 5000 chars), style (max 1000 chars), title (max 80 chars)
- **V4**: prompt (max 3000 chars), style (max 200 chars), title (max 80 chars)
- 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 instrumental setting
- prompt length limit: 500 characters
- Other parameters should be left empty
### Developer Notes
1. Recommended settings for new users: Set customMode to false,
instrumental to false, and only provide prompt and uploadUrl. This is
the simplest configuration to quickly test the API and experience the
results.
2. Generated files will be deleted after 15 days
3. Ensure all required parameters are provided based on customMode and
instrumental settings to avoid errors
4. Pay attention to character limits for prompt, style, and title to
ensure successful processing
5. Callback process has three stages: text (text generation complete),
first (first track complete), complete (all tracks complete)
6. You can use the Get Music Generation Details endpoint to actively
check task status instead of waiting for callbacks
7. The uploadUrl parameter is used to specify the upload location of the
audio file; please provide a valid URL.
operationId: upload-and-cover-audio
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- customMode
- instrumental
- callBackUrl
- model
- prompt
properties:
uploadUrl:
type: string
format: uri
description: >-
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. Note: For the V4_5ALL model, the uploaded audio must
not exceed 1 minute in length.
example: https://storage.example.com/upload
prompt:
type: string
description: >-
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**: 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:
type: string
description: >-
The music style or genre for the audio.
- Required in Custom Mode (`customMode: true`). Examples:
"Jazz", "Classical", "Electronic". Character limits by
model:
- **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:
type: string
description: >-
The title of the generated music track.
- Required in Custom Mode (`customMode: true`). Character
limits by model:
- **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:
type: boolean
description: >-
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:
type: boolean
description: >-
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:
type: string
description: |-
The AI model version to use for generation.
- Required for all requests.
- Available options:
- **`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.
enum:
- V4
- V4_5
- V4_5PLUS
- V4_5ALL
- V5
example: V4
negativeTags:
type: string
description: >-
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:
type: string
format: uri
description: >-
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](https://docs.apikley.ru/suno-api/upload-and-cover-audio-callbacks)
- Alternatively, use the Get Music Details endpoint to poll
task status
example: https://api.example.com/callback
vocalGender:
type: string
description: >-
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.
enum:
- m
- f
example: m
styleWeight:
type: number
description: >-
Strength of adherence to the specified style. Optional.
Range 0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: >-
Controls experimental/creative deviation. Optional. Range
0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: >-
Balance weight for audio features vs. other factors.
Optional. Range 0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
personaId:
type: string
description: >-
Only available when Custom Mode (`customMode: true`) is
enabled. Persona 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](https://docs.apikley.ru/suno-api/generate-persona)
endpoint to create a personalized music Persona based on
generated music.
example: persona_123
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: >-
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
msg:
type: string
description: Error message when code != 200
example: success
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: Task ID for tracking task status
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: >-
System will call this callback when audio generation is
complete.
### Callback Example
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "e231****-****-****-****-****8cadc7dc",
"audio_url": "https://example.cn/****.mp3",
"source_audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"source_stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"source_image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] Night city lights shining bright",
"model_name": "chirp-v3-5",
"title": "Iron Man",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
},
{
"id": "bd15****1873",
"audio_url": "https://example.cn/****.mp3",
"source_audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"source_stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"source_image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] Night city lights shining bright",
"model_name": "chirp-v3-5",
"title": "Iron Man",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 228.28
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Status code
example: 200
msg:
type: string
description: Response message
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
Callback type: text (text generation complete),
first (first track complete), complete (all
tracks complete)
enum:
- text
- first
- complete
task_id:
type: string
description: Task ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: Audio unique identifier (audioId)
audio_url:
type: string
description: Audio file URL
source_audio_url:
type: string
description: Original audio file URL
stream_audio_url:
type: string
description: Streaming audio URL
source_stream_audio_url:
type: string
description: Original streaming audio URL
image_url:
type: string
description: Cover image URL
source_image_url:
type: string
description: Original cover image URL
prompt:
type: string
description: Generation prompt/lyrics
model_name:
type: string
description: Model name used
title:
type: string
description: Music title
tags:
type: string
description: Music tags
createTime:
type: string
description: Creation time
format: date-time
duration:
type: number
description: Audio duration (seconds)
responses:
'200':
description: Callback received successfully
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: >-
Response status code
- **200**: Success - Request has been
processed successfully
- **400**: Validation Error - Lyrics contained
copyrighted material.
- **408**: Rate Limited - Timeout.
- **413**: Conflict - Uploaded audio matches
existing work of art.
- **500**: Server Error - An unexpected error
occurred while processing the request
- **501**: Audio generation failed.
- **531**: Server Error - Sorry, the
generation failed due to an issue. Your
credits have been refunded. Please try again.
msg:
type: string
description: Error message when code != 200
example: success
example:
code: 200
msg: success
components:
responses:
Error:
description: Server Error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
All APIs require authentication via Bearer Token.
Get API Key:
1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
API Key
Usage:
Add to request header:
Authorization: Bearer APIKLEY_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
in the management page
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt