curl --request POST \
  --url https://api.evolink.ai/v1/audios/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno-v5-beta",
  "prompt": "A cheerful summer pop song about road trips and freedom"
}
'

{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5-beta",
  "object": "audio.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 120
  },
  "type": "audio",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 10,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: suno-v5-beta",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "No available channel for the requested model",
    "type": "api_error"
  }
}

Suno

Suno Music Generation Beta

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)
Supports Persona for reusable vocal/style characteristics
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

POST

audios

generations

curl --request POST \
  --url https://api.evolink.ai/v1/audios/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno-v5-beta",
  "prompt": "A cheerful summer pop song about road trips and freedom"
}
'

{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5-beta",
  "object": "audio.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 120
  },
  "type": "audio",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 10,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: suno-v5-beta",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "No available channel for the requested model",
    "type": "api_error"
  }
}

Authorizations

Authorization

string

header

required

##All APIs require Bearer Token authentication##

Get API Key:

Visit API Key Management Page to get your API Key

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

required

Model name

Backward compatibility: Previously integrated model names (e.g. suno-v5, suno-v4.5, suno-v4.5plus, suno-v4.5all, suno-v4) are still supported and will be automatically mapped to the corresponding -beta versions

Available options:

suno-v5.5-beta: V5.5 with models tailored to your unique taste, prompt max 5000 characters, style max 1000 characters; compatible model name: suno-v5.5
suno-v5-beta: V5 latest version (default recommended), supports Voice Persona, superior musical expression, faster generation, prompt max 5000 characters, style max 1000 characters
suno-v4.5plus-beta: V4.5+ enhanced version, richer tones, new creative methods, up to 8 minutes, prompt max 5000 characters, style max 1000 characters
suno-v4.5all-beta: V4.5 full-featured version, smarter prompts, faster generation, up to 8 minutes, prompt max 5000 characters, style max 1000 characters
suno-v4.5-beta: V4.5 version, smarter prompts, faster generation, up to 8 minutes, prompt max 5000 characters, style max 1000 characters
suno-v4-beta: V4 version, improved vocal quality, up to 4 minutes, prompt max 3000 characters, style max 200 characters

Available options:

suno-v5.5-beta,

suno-v5-beta,

suno-v4.5plus-beta,

suno-v4.5all-beta,

suno-v4.5-beta,

suno-v4-beta

Example:

"suno-v5-beta"

custom_mode

boolean

default:false

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)

Simple mode (custom_mode=false) supports only prompt: style, title, negative_tags, vocal_gender, style_weight, weirdness_constraint, audio_weight, persona_id, persona_model, duration are all unsupported in this mode. The API is not guaranteed to reject them, but they have no effect whatsoever on the generated result — use custom_mode=true if you need fine-grained control

Example:

false

instrumental

boolean

default:false

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

string

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

string

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

Unsupported in simple mode (custom_mode=false): in that mode the style is generated automatically by the AI from prompt, so sending this parameter has no effect.

Example:

"pop, electronic, upbeat, female vocals"

title

string

Song title

Description:

Required in custom mode (custom_mode=true)
Will be displayed in the player interface and filename
Max length: 80 characters

Unsupported in simple mode (custom_mode=false): in that mode the title is generated automatically by the AI, so sending this parameter has no effect.

Maximum string length: 80

Example:

"Summer Dreams"

negative_tags

string

Excluded styles, specify music styles or features to avoid

Description:

Max length: 200 characters (same for all models)

Examples:

heavy metal, screaming, sad
rap, fast tempo

Supported only when custom_mode=true; sending it in simple mode has no effect.

Maximum string length: 200

Example:

"heavy metal, screaming"

vocal_gender

enum<string>

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
Unsupported in simple mode (custom_mode=false); sending it has no effect

Available options:

m,

f

Example:

"f"

style_weight

number

Style weight, controls adherence to the specified style

Range: 0.0 ~ 1.0, up to two decimal places and a multiple of 0.01

Description:

Higher values result in closer adherence to the specified style
0 is a valid value, means no adherence to the specified style, and is sent to the model

Supported only when custom_mode=true; sending it in simple mode has no effect.

Required range: 0 <= x <= 1Must be a multiple of 0.01

Example:

0.7

weirdness_constraint

number

Weirdness constraint, controls the creativity/experimental degree of the output

Range: 0.0 ~ 1.0, up to two decimal places and a multiple of 0.01

Description:

Higher values result in more creative and experimental output
Lower values result in more traditional and conservative output
0 is a valid value and is sent to the model

Supported only when custom_mode=true; sending it in simple mode has no effect.

Required range: 0 <= x <= 1Must be a multiple of 0.01

Example:

0.3

audio_weight

number

Audio weight, controls the weight of audio features

Range: 0.0 ~ 1.0, up to two decimal places and a multiple of 0.01

Description:

0 is a valid value and is sent to the model

Supported only when custom_mode=true; sending it in simple mode has no effect.

Required range: 0 <= x <= 1Must be a multiple of 0.01

Example:

0.5

persona_id

string

Persona ID to apply a previously created Persona style to this music generation

Only available when custom_mode=true. Obtained via the Suno Persona Creation API, preserves consistent vocal and style characteristics

How to obtain: After the Persona creation task completes, retrieve from result_data.persona_id

Unsupported in simple mode (custom_mode=false).

Only supported by V5-family models (suno-v5-beta / suno-v5.5-beta, including their compatible non--beta names); sending it with any other model returns a parameter error.

Example:

"5c57d49ef834110496fae5aa14fec441"

persona_model

enum<string>

Persona application mode

Options:

style_persona: Style-oriented, emphasizing musical style characteristics (arrangement, rhythm, timbre)
voice_persona: Voice-oriented, emphasizing vocal characteristics (timbre, singing style, voice)

Both modes are available only with V5-family models (suno-v5-beta / suno-v5.5-beta, including their compatible non--beta names) and require custom_mode=true. It must be used together with persona_id: sending persona_model on its own without persona_id has no effect (persona_id may be used on its own).

Available options:

style_persona,

voice_persona

Example:

"style_persona"

duration

integer

default:20

Requested audio duration in seconds

Available only when the model is suno-v5.5-beta (or compatible name suno-v5.5) and custom_mode=true. Must be an integer from 10 to 360. When omitted, the upstream default is 20 seconds. Other models and simple mode do not support it; sending it returns a parameter error.

Required range: 10 <= x <= 360

Example:

120

callback_url

string<uri>

HTTPS callback URL for terminal task status

Callback timing:

GroAPI sends one callback only when the task reaches a terminal state: completed, failed, or cancelled
Upstream intermediate stages such as text and first are not forwarded
The callback body matches the task detail structure returned by GET /v1/tasks/{id}

Security restrictions:

HTTPS only
Callbacks to internal IP addresses are prohibited
URL length must not exceed 2048 characters

Callback mechanism:

Per-attempt timeout: 10 seconds
Up to 3 retries after the initial request fails
A 2xx response is considered successful

Example:

"https://your-domain.com/webhooks/suno-callback"

Response

Music task created successfully

created

integer

Task creation timestamp

Example:

1766319090

string

Task ID, used to query task status and results

Example:

"task-unified-1766319089-oqs9cue4"

model

string

Actual model name used

Example:

"suno-v5-beta"

object

enum<string>

Task type

Available options:

audio.generation.task

progress

integer

Task progress percentage (0-100)

Required range: 0 <= x <= 100

Example:

0

status

enum<string>

Task status

Available options:

pending,

processing,

completed,

failed,

cancelled

Example:

"pending"

task_info

object

Audio task details

Show child attributes

type

enum<string>

Task output type

Available options:

audio

Example:

"audio"

usage

object

Usage and billing information

Show child attributes

Image Series

Video Series

Audio Series

Text Series

Account Management

Task Management

File Management

Suno Music Generation Beta

Authorizations

Body

Response