Suno Music Generation
- Suno AI music generation model, supports generating complete music based on text descriptions or lyrics
- Supports custom mode (fine control over style, title, lyrics) and simple mode (AI auto-generation)
- Asynchronous processing mode, use the returned task ID to query status
- Generated audio links are valid for 72 hours, please save them promptly
- Each request generates multiple music variations
OpenAPI
````yaml en/api-manual/audio-series/suno/suno-music-generation.json post /v1/audios/generations openapi: 3.1.0 info: title: Suno Music Generation API description: >- Generate music using Suno AI models, supporting both vocal and instrumental modes license: name: MIT version: 1.0.0 servers: - url: https://ai.odkkk.com/apiv1 description: Production Environment security: - bearerAuth: [] paths: /v1/audios/generations: post: tags: - Audio Generation summary: Suno Music Generation API description: >- - Suno AI music generation model, supports generating complete music based on text descriptions or lyrics
- Supports custom mode (fine control over style, title, lyrics) and
simple mode (AI auto-generation)
- Asynchronous processing mode, use the returned task ID to [query
status](/en/api-manual/task-management/get-task-detail)
- Generated audio links are valid for 72 hours, please save them
promptly
- Each request generates multiple music variations
operationId: createSunoMusicGeneration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SunoMusicGenerationRequest'
examples:
simple_mode:
summary: Simple Mode (Recommended for beginners)
value:
model: suno-v4.5
prompt: A cheerful summer pop song about road trips and freedom
custom_mode_with_lyrics:
summary: Custom Mode (with lyrics)
value:
model: suno-v4.5
custom_mode: true
instrumental: false
style: pop, electronic, upbeat, female vocals, 120bpm
title: Summer Dreams
prompt: |-
[Verse 1]
Driving down the highway, windows down
The sun is shining on this little town
Radio playing our favorite song
Nothing could ever go wrong
[Chorus]
Summer dreams, summer nights
Chasing stars and city lights
With you by my side
I feel so alive
negative_tags: heavy metal, screaming, sad
vocal_gender: f
instrumental_mode:
summary: Instrumental Mode
value:
model: suno-v4.5plus
custom_mode: true
instrumental: true
style: lo-fi, chill, ambient, piano, soft drums
title: Rainy Afternoon
responses:
'200':
description: Music task created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AudioGenerationResponse'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 400
message: style is required when custom_mode is true
type: invalid_request_error
param: style
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 401
message: Invalid authentication credentials
type: authentication_error
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 403
message: Access denied for this model
type: permission_error
param: model
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 404
message: Specified model not found
type: not_found_error
param: model
fallback_suggestion: suno-v4.5
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 429
message: Rate limit exceeded
type: rate_limit_error
fallback_suggestion: retry after 60 seconds
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 500
message: Internal server error
type: internal_server_error
fallback_suggestion: try again later
'502':
description: Upstream service error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 502
message: Bad gateway
type: upstream_error
fallback_suggestion: try again later
'503':
description: Service temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 503
message: Service temporarily unavailable
type: service_unavailable_error
fallback_suggestion: retry after 30 seconds
components: schemas: SunoMusicGenerationRequest: type: object required: - model - custom_mode - instrumental properties: model: type: string description: >- Model name
**Available options:**
- `suno-v4`: V4 version, improved vocal quality, up to 4 minutes,
prompt max `3000` characters, style max `200` characters
- `suno-v4.5`: V4.5 version (Recommended), smarter prompts, faster
generation, up to 8 minutes, prompt max `5000` characters, style max
`1000` characters
- `suno-v4.5plus`: V4.5+ enhanced version, richer tones, new
creative methods, up to 8 minutes, prompt max `5000` characters,
style max `1000` characters
- `suno-v4.5all`: V4.5 full-featured version, smarter prompts,
faster generation, up to 8 minutes, prompt max `5000` characters,
style max `1000` characters
- `suno-v5`: V5 latest version, superior musical expression, faster
generation, prompt max `5000` characters, style max `1000`
characters
enum:
- suno-v4
- suno-v4.5
- suno-v4.5plus
- suno-v4.5all
- suno-v5
example: suno-v4.5
custom_mode:
type: boolean
description: >-
Enable custom mode
**Description:**
- `false`: Simple mode, only provide `prompt`, AI auto-generates
lyrics and style
- `true`: Custom mode, allows fine control over `style`, `title`,
lyrics, etc.
**Required parameters in custom mode:**
- `style`: Required
- `title`: Required
- `prompt`: Required when `instrumental=false` (used as lyrics)
example: false
instrumental:
type: boolean
description: |-
Generate instrumental music (no vocals)
**Description:**
- `false`: Generate music with vocals
- `true`: Generate instrumental/background music without vocals
**Note:**
- In non-custom mode, this parameter doesn't affect required fields
- In custom mode, when set to `true`, `prompt` becomes optional
example: false
prompt:
type: string
description: >-
Prompt describing the desired music content
**Non-custom mode (`custom_mode=false`):**
- Required, serves as music description, AI auto-generates lyrics
and style
- Max length: `500` characters
**Custom mode (`custom_mode=true`):**
- Required when `instrumental=false`, used as exact lyrics
- Optional when `instrumental=true`
- Max length: `3000` characters for V4, `5000` characters for V4.5+
**Lyrics format suggestions:**
- Use tags like `[Verse]`, `[Chorus]`, `[Bridge]` to organize lyrics
structure
example: A cheerful summer pop song about road trips and freedom
style:
type: string
description: >-
Music style specification
**Description:**
- Required in custom mode (`custom_mode=true`)
- Defines the genre, mood, or artistic direction of the music
- Recommended to use comma-separated tags in English
**Character limits:**
- V4: Max `200` characters
- V4.5+: Max `1000` characters
**Common style tags:**
- Genres: pop, rock, jazz, classical, electronic, hip-hop, r&b,
country, folk
- Moods: happy, sad, energetic, calm, romantic, dark, uplifting
- Instruments: piano, guitar, drums, bass, violin, saxophone,
synthesizer
- Vocals: male vocals, female vocals, choir, harmonies
- Tempo: slow, fast, upbeat, groovy, 120bpm
example: pop, electronic, upbeat, female vocals
title:
type: string
description: |-
Song title
**Description:**
- Required in custom mode (`custom_mode=true`)
- Will be displayed in the player interface and filename
- Max length: `80` characters
maxLength: 80
example: Summer Dreams
negative_tags:
type: string
description: |-
Excluded styles, specify music styles or features to avoid
**Examples:**
- `heavy metal, screaming, sad`
- `rap, fast tempo`
example: heavy metal, screaming
vocal_gender:
type: string
description: >-
Vocal gender preference
**Options:**
- `m`: Male voice
- `f`: Female voice
**Note:**
- Only effective when `custom_mode=true`
- This parameter only increases the probability, cannot guarantee
the specified gender will be followed
enum:
- m
- f
example: f
style_weight:
type: number
description: |-
Style weight, controls adherence to the specified style
**Range:** `0.0` ~ `1.0`, one decimal place
**Description:**
- Higher values result in closer adherence to specified style
- Value of `0` is treated as unset
minimum: 0
maximum: 1
example: 0.7
weirdness_constraint:
type: number
description: >-
Weirdness constraint, controls the creativity/experimental degree of
the output
**Range:** `0.0` ~ `1.0`, one decimal place
**Description:**
- Higher values result in more creative and experimental output
- Lower values result in more traditional and conservative output
- Value of `0` is treated as unset
minimum: 0
maximum: 1
example: 0.3
audio_weight:
type: number
description: |-
Audio weight, controls the weight of audio features
**Range:** `0.0` ~ `1.0`, one decimal place
**Description:**
- Value of `0` is treated as unset
minimum: 0
maximum: 1
example: 0.5
callback_url:
type: string
description: >-
HTTPS callback URL for task completion notification
**Callback stages:**
- Callback process has three stages: `text` (text generation),
`first` (first track completed), `complete` (all completed)
- In some cases, `text` and `first` stages may be skipped, returning
`complete` directly
**Security restrictions:**
- Only HTTPS protocol supported
- Callbacks to internal IP addresses are prohibited
- URL length must not exceed `2048` characters
**Callback mechanism:**
- Timeout: `10` seconds
- Max `3` retries on failure
- Callback URL returning 2xx status code is considered successful
format: uri
example: https://your-domain.com/webhooks/suno-callback
AudioGenerationResponse:
type: object
properties:
created:
type: integer
description: Task creation timestamp
example: 1766319090
id:
type: string
description: Task ID, used to query task status and results
example: task-unified-1766319089-oqs9cue4
model:
type: string
description: Actual model name used
example: suno-v5
object:
type: string
enum:
- audio.generation.task
description: Task type
progress:
type: integer
description: Task progress percentage (0-100)
minimum: 0
maximum: 100
example: 100
result_data:
type: array
description: Generated music details array, returned when task is completed
items:
$ref: '#/components/schemas/AudioResultItem'
results:
type: array
description: Generated audio URL array, returned when task is completed
items:
type: string
format: uri
example:
- https://media.evolink.ai/xxx.mp3
- https://media.evolink.ai/yyy.mp3
status:
type: string
description: Task status
enum:
- pending
- processing
- completed
- failed
example: completed
task_info:
$ref: '#/components/schemas/AudioTaskInfo'
description: Audio task details
type:
type: string
enum:
- audio
description: Task output type
example: audio
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: integer
description: Error code
message:
type: string
description: Error message
type:
type: string
description: Error type
param:
type: string
description: Parameter that caused the error
fallback_suggestion:
type: string
description: Suggested solution
AudioResultItem:
type: object
description: Single music generation result
properties:
result_id:
type: string
description: Result unique identifier
example: 555f4ea2-cfef-4622-8355-baa5f2ce6a59
duration:
type: number
description: Audio duration (seconds)
example: 91.2
tags:
type: string
description: Music style tags
example: R&B
title:
type: string
description: Song title
example: Forget Me Nots
image_url:
type: string
format: uri
description: Cover image URL
example: https://media.evolink.ai/xxx.jpeg
audio_url:
type: string
format: uri
description: Audio file URL
example: https://media.evolink.ai/xxx.mp3
stream_audio_url:
type: string
format: uri
description: Streaming audio URL
example: https://media.evolink.ai/xxx.mp3
AudioTaskInfo:
type: object
properties:
can_cancel:
type: boolean
description: Whether the task can be cancelled
example: false
securitySchemes: bearerAuth: type: http scheme: bearer description: >- ##All APIs require Bearer Token authentication##
**Get API Key:**
Visit [API Key Management Page](https://ai.odkkk.com/apiv1/dashboard/keys) to
get your API Key
**Add to request header when using:**
```
Authorization: Bearer YOUR_API_KEY
```
````
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://ai.odkkk.com/apiv1/docs/llms.txt