> ## 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.
# Generate Music
> Generate music with or without lyrics using AI models.
### Usage Guide
* This endpoint creates music based on your text prompt
* Multiple variations will be generated for each request
* You can control detail level with custom mode and instrumental settings
### Parameter Details
* In Custom Mode (`customMode: true`):
* If `instrumental: true`: `style` and `title` are required
* If `instrumental: false`: `style`, `prompt`, and `title` are required
* Character limits vary by model:
* **V4**: `prompt` 3000 characters, `style` 200 characters
* **V4\_5, V4\_5PLUS, V5, V5\_5 & V4\_5ALL**: `prompt` 5000 characters, `style` 1000 characters (**V5\_5**: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same limits as **V5**)
* `title` length limit: 80 characters (all models)
* In Non-custom Mode (`customMode: false`):
* Only `prompt` is 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": false,
"instrumental": false,
"prompt": "A chill lo-fi beat with soft vocals",
"model": "V4_5ALL",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
```
### Developer Notes
* Recommendation for new users: Start with `customMode: false` for simpler usage
* Generated files are retained for 14 days
* Callback process has three stages: `text` (text generation), `first` (first track complete), `complete` (all tracks complete)
## OpenAPI
````yaml suno-api/suno-api.json POST /api/v1/generate
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:
post:
summary: Generate Music
operationId: generate-music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customMode
- instrumental
- callBackUrl
- model
properties:
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). 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".
- 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 and 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 music
generation 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
[Music Generation
Callbacks](https://docs.api.box/suno-api/generate-music-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
````