> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
* 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 (based on model):**
* **V4\_5, V4\_5PLUS, V5, V5\_5 models**: prompt max 5000 characters, style max 1000 characters, title max 100 characters
* **V4 model**: prompt max 3000 characters, style max 200 characters, title max 80 characters
* **V4\_5ALL model**: prompt max 5000 characters, style max 1000 characters, title max 80 characters
* **model** (string, required): `V4_5ALL`, `V4`, `V4_5`, `V4_5PLUS`, `V5`, `V5_5`. **`V5_5`**: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same limits as **`V5`** where applicable.
* 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
### Optional parameters
The following fields are optional controls available for this endpoint:
* vocalGender (string): Preferred vocal gender. Allowed values: `m` (male), `f` (female)
* styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
* weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
* audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
* personaId (string): Persona ID or Suno Voice `voiceId` to apply in Custom Mode. If you use a Voice-generated ID, set `personaModel` to `voice_persona`.
* personaModel (string): Persona type. Use `style_persona` for Generate Persona IDs, or `voice_persona` for Suno Voice IDs.
```json JSON body theme={null}
{
"customMode": true,
"instrumental": false,
"prompt": "Cover with a darker cinematic vibe",
"style": "Cinematic",
"title": "Dark Reprise",
"uploadUrl": "https://storage.example.com/upload",
"model": "V4_5ALL",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
```
### 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.
## OpenAPI
````yaml suno-api/suno-api.json POST /api/v1/generate/upload-cover
openapi: 3.0.0
info:
title: intro
description: API documentation for audio generation services
version: 1.0.0
contact:
name: Technical Support
email: support@api.box
servers:
- url: https://apibox.erweima.ai
description: API Server
security:
- BearerAuth: []
tags:
- name: Music Generation
description: Endpoints for creating and managing music generation tasks
- name: Lyrics Generation
description: Endpoints for lyrics generation and management
- name: WAV Conversion
description: Endpoints for converting music to WAV format
- name: Vocal Removal
description: Endpoints for vocal removal from music tracks
- name: Music Video Generation
description: Endpoints for generating MP4 videos from music tracks
- name: Account Management
description: Endpoints for account and credits management
paths:
/api/v1/generate/upload-cover:
post:
summary: Upload And Cover Audio
operationId: upload-and-cover-audio
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- customMode
- instrumental
- callBackUrl
- model
properties:
uploadUrl:
type: string
format: uri
description: >-
The URL for uploading audio files, required regardless of
whether customMode and instrumental are true or false.
**Upload Audio Duration Limits:** Maximum upload duration is
**8 minutes**
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:
- **V4**: Maximum 3000 characters
- **V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL**: 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"
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".
- For V4 model: Max length: 200 characters.
- For V4_5, V4_5PLUS, V5, V5_5 and V4_5ALL models: Max length: 1000 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:
- **V4 & V4_5ALL**: Max length: 80 characters
- **V4_5, V4_5PLUS, V5 & V5_5**: Max length: 100 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
personaId:
type: string
description: >-
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](https://docs.api.box/suno-api/generate-persona)
endpoint. Use `personaModel: style_persona` or omit
`personaModel` to use the default.
- A `voiceId` generated by the [Suno
Voice](https://docs.api.box/suno-api/suno-voice-generate)
workflow. When using a voice-generated ID, you must set
`personaModel: voice_persona`.
example: persona_123
personaModel:
type: string
description: >-
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.
enum:
- style_persona
- voice_persona
default: style_persona
example: style_persona
model:
type: string
description: |-
The AI model version to use for generation.
- Required for all requests.
- Available options:
- **`V5`**: Superior musical expression, faster generation.
- **`V5_5`**: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. Same custom-mode `prompt` and `style` character limits as **V5** (5000 / 1000).
- **`V4_5PLUS`**: V4.5+ is richer sound, new waysto create, max 8 min.
- **`V4_5`**: V4.5 is smarter prompts, fastergenerations, max 8 min.
- **`V4`**: V4 is improved vocal quality,max 4 min.
- **`V4_5ALL`**: V4.5-all is better song structure,max 8 min.
enum:
- V4_5ALL
- V4
- V4_5
- V4_5PLUS
- V5
- V5_5
example: V4_5ALL
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 task completion notifications when upload
and cover audio is complete. The callback process has three
stages: `text` (text generation), `first` (first track
complete), `complete` (all tracks complete). Note: In some
cases, `text` and `first` stages may be skipped, directly
returning `complete`.
- For detailed callback format and implementation guide, see
[Upload and Cover Audio
Callbacks](https://docs.api.box/suno-api/upload-and-cover-audio-callbacks)
- Alternatively, you can use the Get Music Generation
Details interface to poll task status
example: https://api.example.com/callback
vocalGender:
type: string
description: >-
Preferred vocal gender. Optional. Allowed values: 'm'
(male), 'f' (female).
enum:
- m
- f
example: m
styleWeight:
type: number
description: >-
Style adherence weight. Optional. Range: 0-1. Two decimal
places recommended.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: >-
Creativity/novelty constraint. Optional. Range: 0-1. Two
decimal places recommended.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: >-
Relative weight of audio consistency versus other controls.
Optional. Range: 0-1. Two decimal places recommended.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- 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": "8551****662c",
"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
method: post
type: path
path: '{request.body#/callBackUrl}'
components:
schemas:
ApiResponse:
type: object
properties:
code:
type: integer
description: |-
# 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
example: 200
enum:
- 200
- 400
- 401
- 404
- 405
- 413
- 429
- 430
- 455
- 500
msg:
type: string
description: Error message when code != 200
example: success
responses:
Error:
description: Server error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
# 🔑 API Authentication
All endpoints require authentication using Bearer Token.
## Get API Key
1. Visit the [API Key Management Page](https://api.box/api-key) 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
````