Suno 音乐生成 Beta

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": "一首欢快的夏日流行歌曲，关于公路旅行和自由"
}
'

{
  "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"
  }
}

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": "一首欢快的夏日流行歌曲，关于公路旅行和自由"
}
'

{
  "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"
  }
}

授权

Authorization

string

header

必填

##所有接口均需要使用Bearer Token进行认证##

获取 API Key ：

访问 API Key 管理页面获取您的 API Key

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求体

application/json

model

enum<string>

必填

模型名称

向后兼容：之前接入的模型名（如 suno-v5、suno-v4.5、suno-v4.5plus、suno-v4.5all、suno-v4）仍然可用，会自动映射到对应的 -beta 版本

可选值：

suno-v5.5-beta: V5.5版本，支持按独特偏好定制，prompt最多5000字符，style最多1000字符；兼容模型名：suno-v5.5
suno-v5-beta: V5最新版本（默认推荐），支持 Voice Persona，更卓越的音乐表现力，生成速度更快，prompt最多5000字符，style最多1000字符
suno-v4.5plus-beta: V4.5+增强版，音色更丰富，新的创作方式，最长8分钟，prompt最多5000字符，style最多1000字符
suno-v4.5all-beta: V4.5全功能版，更智能的提示词，更快的生成速度，最长8分钟，prompt最多5000字符，style最多1000字符
suno-v4.5-beta: V4.5版本，更智能的提示词，更快的生成速度，最长8分钟，prompt最多5000字符，style最多1000字符
suno-v4-beta: V4版本，改进的人声质量，最长4分钟，prompt最多3000字符，style最多200字符

可用选项:

suno-v5.5-beta,

suno-v5-beta,

suno-v4.5plus-beta,

suno-v4.5all-beta,

suno-v4.5-beta,

suno-v4-beta

示例:

"suno-v5-beta"

custom_mode

boolean

默认值:false

是否开启自定义模式

说明：

false：简单模式，只需提供prompt，AI自动生成歌词和风格
true：自定义模式，可精细控制style、title、歌词等

自定义模式下的必填参数：

style: 必填
title: 必填
prompt: 当instrumental=false时必填（作为歌词）

简单模式（custom_mode=false）仅支持 prompt： style、title、negative_tags、vocal_gender、style_weight、weirdness_constraint、audio_weight、persona_id、persona_model、duration 在该模式下均不受支持。接口不保证一定拒绝，但这些参数不会对生成结果产生任何影响——需要精细控制请改用 custom_mode=true

示例:

false

instrumental

boolean

默认值:false

是否生成纯音乐（无人声）

说明：

false：生成带人声的音乐
true：生成无人声的纯音乐/背景音乐

注意：

在非自定义模式下，此参数对必填字段无影响
在自定义模式下，设为true时prompt变为可选

示例:

false

prompt

string

提示词，描述所需音乐内容

非自定义模式（custom_mode=false）：

必填，作为音乐描述，AI自动生成歌词和风格
最大长度：500字符

自定义模式（custom_mode=true）：

当instrumental=false时必填，作为精确歌词使用
当instrumental=true时可选
最大长度：V4为3000字符，V4.5+为5000字符

歌词格式建议：

使用[Verse]、[Chorus]、[Bridge]等标签组织歌词结构

示例:

"一首欢快的夏日流行歌曲，关于公路旅行和自由"

style

string

音乐风格规范

说明：

在自定义模式（custom_mode=true）下必填
定义音乐的流派、情绪或艺术方向
建议使用英文逗号分隔的标签形式

字符限制：

V4：最多200字符
V4.5+：最多1000字符

常见风格标签：

流派：pop, rock, jazz, classical, electronic, hip-hop, r&b, country, folk
情绪：happy, sad, energetic, calm, romantic, dark, uplifting
乐器：piano, guitar, drums, bass, violin, saxophone, synthesizer
人声：male vocals, female vocals, choir, harmonies
节奏：slow, fast, upbeat, groovy, 120bpm

简单模式（custom_mode=false）下不受支持：该模式的风格由 AI 依据 prompt 自动生成，传入本参数不会生效。

示例:

"pop, electronic, upbeat, female vocals"

title

string

歌曲标题

说明：

在自定义模式（custom_mode=true）下必填
将显示在播放器界面和文件名中
最大长度：80字符

简单模式（custom_mode=false）下不受支持：该模式的标题由 AI 自动生成，传入本参数不会生效。

Maximum string length: 80

示例:

"夏日梦想"

negative_tags

string

排除风格，指定不希望出现的音乐风格或特征

说明：

最大长度：200 字符（所有模型一致）

示例：

heavy metal, screaming, sad
rap, fast tempo

仅在 custom_mode=true 时受支持；简单模式下传入不会生效。

Maximum string length: 200

示例:

"heavy metal, screaming"

vocal_gender

enum<string>

人声性别偏好

可选值：

m: 男声
f: 女声

注意：

仅在custom_mode=true时生效
此参数只能加强概率，不能保证一定遵循指定性别
简单模式（custom_mode=false）下不受支持，传入不会生效

可用选项:

m,

f

示例:

"f"

style_weight

number

风格权重，控制对指定风格的遵循强度

取值范围： 0.0 ~ 1.0，最多保留两位小数，必须是 0.01 的倍数

说明：

值越高，生成结果越接近指定风格
0 是有效值，表示完全不遵循指定风格，并会真实下发给模型

仅在 custom_mode=true 时受支持；简单模式下传入不会生效。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.7

weirdness_constraint

number

怪异度约束，控制生成结果的创意/实验性程度

取值范围： 0.0 ~ 1.0，最多保留两位小数，必须是 0.01 的倍数

说明：

值越高，生成结果越具有创意和实验性
值越低，生成结果越传统和保守
0 是有效值，并会真实下发给模型

仅在 custom_mode=true 时受支持；简单模式下传入不会生效。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.3

audio_weight

number

音频权重，控制音频特征的权重

取值范围： 0.0 ~ 1.0，最多保留两位小数，必须是 0.01 的倍数

说明：

0 是有效值，并会真实下发给模型

仅在 custom_mode=true 时受支持；简单模式下传入不会生效。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.5

persona_id

string

Persona ID，应用已创建的 Persona 风格到本次音乐生成

仅在 custom_mode=true 时可用。通过 Suno Persona 创建接口获得，应用后可保持一致的声乐和风格特征

获取方式：创建 Persona 任务完成后，从 result_data.persona_id 中获取

简单模式（custom_mode=false）下不受支持。

仅支持 V5 系模型（suno-v5-beta / suno-v5.5-beta，以及对应的不带 -beta 兼容名称）；在其他模型上传入会返回参数错误。

示例:

"5c57d49ef834110496fae5aa14fec441"

persona_model

enum<string>

Persona 应用方式

可选值：

style_persona: 风格导向型，偏重音乐风格特征（编曲、节奏、音色）
voice_persona: 声音导向型，偏重声乐特征（音色、唱法、声线）

两种方式都仅支持 V5 系模型（suno-v5-beta / suno-v5.5-beta，以及对应的不带 -beta 兼容名称），且仅在 custom_mode=true 时可用。必须与 persona_id 搭配使用：单独传入 persona_model 而不传 persona_id 不会生效（persona_id 可以单独使用）。

可用选项:

style_persona,

voice_persona

示例:

"style_persona"

duration

integer

默认值:20

期望的音频时长（秒）

仅当模型为 suno-v5.5-beta（或兼容名称 suno-v5.5）且 custom_mode=true 时可用。取值必须是 10 到 360 之间的整数；省略时由上游使用默认值 20 秒。其他模型或简单模式下不受支持，传入会返回参数错误。

必填范围: 10 <= x <= 360

示例:

120

callback_url

string<uri>

任务终态的 HTTPS 回调地址

回调时机：

GroAPI 仅在任务进入终态时回调一次：completed、failed 或 cancelled
不会发送上游的 text、first 等中间阶段回调
回调主体与 GET /v1/tasks/{id} 的任务详情结构保持一致

安全限制：

仅支持 HTTPS 协议
禁止回调到内网 IP 地址
URL 长度不超过 2048 字符

回调机制：

单次超时时间：10 秒
初次请求失败后最多重试 3 次
回调地址返回 2xx 状态码视为成功

示例:

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

响应

音乐任务创建成功

created

integer

任务创建时间戳

示例:

1766319090

string

任务ID，用于查询任务状态和结果

示例:

"task-unified-1766319089-oqs9cue4"

model

string

实际使用的模型名称

示例:

"suno-v5-beta"

object

enum<string>

任务的具体类型

可用选项:

audio.generation.task

progress

integer

任务进度百分比 (0-100)

必填范围: 0 <= x <= 100

示例:

0

status

enum<string>

任务状态

可用选项:

pending,

processing,

completed,

failed,

cancelled

示例:

"pending"

task_info

object

任务详细信息

Show child attributes

type

enum<string>

任务的输出类型

可用选项:

audio

示例:

"audio"

usage

object

使用量和计费信息

Show child attributes

图像系列

视频系列

音频系列

语言系列

账户管理

任务管理

文件管理

Suno 音乐生成 Beta

授权

请求体

响应