Skip to main content
POST
/
v1
/
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"
  }
}

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-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-beta,
suno-v4.5plus-beta,
suno-v4.5all-beta,
suno-v4.5-beta,
suno-v4-beta
Example:

"suno-v5-beta"

​
custom_mode
boolean
required

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
boolean
required

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
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
Maximum string length: 80
Example:

"Summer Dreams"

​
negative_tags
string

Excluded styles, specify music styles or features to avoid

Examples:

  • heavy metal, screaming, sad
  • rap, fast tempo
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
Available options:
m,
f
Example:

"f"

​
style_weight
number

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
Required range: 0 <= x <= 1
Example:

0.7

​
weirdness_constraint
number

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
Required range: 0 <= x <= 1
Example:

0.3

​
audio_weight
number

Audio weight, controls the weight of audio features

Range: 0.0 ~ 1.0, one decimal place

Description:

  • Value of 0 is treated as unset
Required range: 0 <= x <= 1
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

Example:

"5c57d49ef834110496fae5aa14fec441"

​
persona_model
enum<string>

Persona application mode

Options:

  1. style_persona: Style-oriented, emphasizes musical style characteristics (arrangement, rhythm, timbre), supports all model versions
  2. voice_persona: Voice-oriented, emphasizes vocal characteristics (timbre, singing style, voice), V5 only

Only available when custom_mode=true, typically used with persona_id. When using voice_persona, the model must be suno-v5-beta, otherwise an error is returned

Available options:
style_persona,
voice_persona
Example:

"style_persona"

​
callback_url
string<uri>

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
Example:

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

Response

Music task created successfully

​
created
integer

Task creation timestamp

Example:

1766319090

​
id
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
Example:

"pending"

​
task_info
object

Audio task details

​
type
enum<string>

Task output type

Available options:
audio
Example:

"audio"

​
usage
object

Usage and billing information