> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Suno API: Cover Music
> Cover music tracks to new styles while preserving their core melody. It integrates Suno's upload feature, and the expected result is to generate tracks in new styles with the original melody unchanged.
### Important Notes
* Requires an `audio_url` pointing to the uploaded audio file
* For existing music, suno may fail to upload.
* Supports two modes: `simple` and `custom`
* In `simple` mode, `prompt` is required
* In `custom` mode, `title` and `tags` are required, and `lyrics` is required if `instrumental=false`
If you want a quick cover based on the uploaded audio, start with `mode=simple`.
### Music Cover (Simple Mode)
Create a cover from the uploaded music using a short prompt.
```json simple cover theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "simple",
"model": "v5",
"instrumental": false,
"prompt": "Create a cover with a softer, more intimate vocal delivery."
}
}
```
```json instrumental cover theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "simple",
"model": "v5",
"instrumental": true,
"prompt": "Instrumental cover with warm piano and gentle ambience."
}
}
```
### Music Cover (Custom Mode)
Custom cover lets you control style and lyrics. Provide `title`, `tags`, and `lyrics` (unless instrumental).
```json custom cover theme={null} theme={null}
{
"model": "suno/music-cover",
"callback_url": "",
"input": {
"audio_url": "https://example.com/uploaded-audio.mp3",
"mode": "custom",
"model": "v5",
"instrumental": false,
"title": "Midnight Addiction (Cover)",
"tags": "Western R&B, female vocal, dark, sensual",
"lyrics": "[Verse 1]\nI still taste your words in the dark...",
"vocal_gender": "f",
"style_weight": 0.85,
"audio_weight": 0.6,
"weirdness_constraint": 0.2,
"negative_tags": "metal, aggressive"
}
}
```
### Get Task Result
After submitting a task, use the unified query endpoint to check progress and retrieve results:
Learn how to query suno task status and retrieve generation results
## OpenAPI
````yaml suno-api/cover-music.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
title: Crun Suno Music Cover API
description: crun.ai Suno Music Cover API Documentation
version: 1.0.0
contact:
name: Technical Support
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API Server
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/CreateTask:
post:
summary: Suno music cover from uploaded audio
operationId: suno/music-cover
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- suno/music-cover
description: |-
The model name to use for generation. Required field.
- Must be `suno/music-cover` for this endpoint
callback_url:
type: string
format: uri
description: >-
Optional. Callback URL for receiving task completion
notifications.
- System will POST task status and results to this URL when
generation completes
- Callback payloads structure is consistent with the `data`
object returned by the task status query
- Your callback endpoint should accept POST requests with
JSON payload containing results
- It returns an HTTP 200 status code upon successful receipt
example: https://your-domain.com/api/callback
input:
$ref: '#/components/schemas/SunoMusicCoverInput'
example:
model: suno/music-cover
callback_url: https://your-domain.com/api/callback
input:
audio_url: https://example.com/uploaded-audio.mp3
mode: custom
model: v5
instrumental: false
title: Midnight Addiction (Cover)
tags: Western R&B, female vocal, dark, sensual
lyrics: |-
[Verse 1]
I still taste your words in the dark...
vocal_gender: f
style_weight: 0.85
audio_weight: 0.6
weirdness_constraint: 0.2
negative_tags: metal, aggressive
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
task_id:
type: string
description: >-
Task ID, can be used with Get Task Details
endpoint to query task status
example: task_12345678
example:
code: 200
message: success
data:
task_id: task_12345678
'422':
description: Validation Error
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: Detailed validation error messages
items:
type: string
example:
- specific error field message
example:
code: 422
message: Missing Params or Type Error
errors:
- specific error field message
'500':
$ref: '#/components/responses/Error'
components:
schemas:
SunoMusicCoverInput:
type: object
description: |-
Input parameters for music cover based on an uploaded audio file.
Rules:
- `audio_url` is required and must point to the uploaded audio file.
- `mode=simple`: `prompt` is required.
- `mode=custom`: `title` and `tags` are required.
- `mode=custom` and `instrumental=false`: `lyrics` is required.
- `model=v4`: `tags` max length is 200 and `lyrics` max length is 3000.
properties:
audio_url:
type: string
format: uri
description: >-
URL of the reference music file url. Ensure the uploaded audio does
not exceed 8 minutes in length.
example: https://example.com/reference-music.mp3
mode:
type: string
enum:
- simple
- custom
description: Music generation mode.
example: simple
model:
type: string
enum:
- v5.5
- v5
- v4.5plus
- v4.5
- v4.5all
- v4
description: >-
Suno music model version.
- **v5.5**: A tailor-made model crafted to match 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**: enables smarter prompts, faster generations, max 8 min.
- **v4.5all**: enables smarter prompts, faster generations, max 8
min.
- **v4**: improves vocal quality, max 4 min.
example: v5
instrumental:
type: boolean
description: Whether to generate instrumental-only audio (no lyrics).
example: false
title:
type: string
maxLength: 100
description: Music title. Required in `custom` mode.
example: Midnight Addiction (Cover)
prompt:
type: string
maxLength: 500
description: >-
Text prompts for guiding music generation for `simple` mode.
Required when mode is `simple`.
example: Create a cover with a softer, more intimate vocal delivery.
lyrics:
type: string
maxLength: 5000
description: >-
Lyrics for custom mode. Required when mode is `custom` and
`instrumental` is `false`. For model `v4`, max length is 3000,
others 5000.
example: |-
[Verse 1]
I still taste your words in the dark...
tags:
type: string
maxLength: 1000
description: >-
Music style tags. Required in `custom` mode. For model `v4`, max
length is 200, others 1000.
example: Western R&B, female vocal, dark, sensual, slow tempo
vocal_gender:
type: string
enum:
- m
- f
description: >-
Vocal gender preference: `m` for male, `f` for female. Effective
only in `custom` mode.
example: f
negative_tags:
type: string
maxLength: 1000
description: Music styles to exclude.
example: metal, aggressive, harsh vocals
style_weight:
type: number
minimum: 0
maximum: 1
description: Style reference strength, from 0.0 to 1.0.
example: 0.85
audio_weight:
type: number
minimum: 0
maximum: 1
description: Balance weight for audio features vs other factors, from 0.0 to 1.0.
example: 0.6
weirdness_constraint:
type: number
minimum: 0
maximum: 1
description: Controls experimental/creative deviation, from 0.0 to 1.0.
example: 0.2
persona_id:
type: string
description: >-
Persona ID for the selected persona model. Create via [Suno Persona
Generate](/suno-api/suno-persona-generate).
example: persona_123456
persona_model:
type: string
enum:
- style_persona
- voice_persona
description: |-
Persona model type. Use with `persona_id` to apply a saved persona.
- **style_persona**: Applies style-focused persona characteristics.
- **voice_persona**: Applies voice-focused persona characteristics (only available with v5 model).
default: style_persona
example: style_persona
required:
- audio_url
- mode
- model
- instrumental
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
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
- **422**: Validation Error - The request parameters failed
validation checks
- **429**: Rate Limited - Request limit has been exceeded for this
resource
- **455**: Service Unavailable - System is currently undergoing
maintenance
- **500**: Server Error - An unexpected error occurred while
processing the request
- **501**: Generation Failed - Content generation task failed
- **505**: Feature Disabled - The requested feature is currently
disabled
message:
type: string
description: Response message, error description when failed
example: success
responses:
Error:
description: Server Error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
All APIs require authentication via API Key.
Get API Key:
1. Visit [API Key Management Page](https://crun.ai/user-api-key) to get
your API Key
Usage:
Add to request header:
x-api-key: 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
in the management page
````