跳转到主要内容
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-v4.5",
  "prompt": "一首欢快的夏日流行歌曲，关于公路旅行和自由"
}
'
{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5",
  "object": "audio.generation.task",
  "progress": 100,
  "result_data": [
    {
      "result_id": "555f4ea2-cfef-4622-8355-baa5f2ce6a59",
      "duration": 91.2,
      "tags": "R&B",
      "title": "Forget Me Nots",
      "image_url": "https://media.evolink.ai/xxx.jpeg",
      "audio_url": "https://media.evolink.ai/xxx.mp3",
      "stream_audio_url": "https://media.evolink.ai/xxx.mp3"
    }
  ],
  "results": [
    "https://media.evolink.ai/xxx.mp3",
    "https://media.evolink.ai/yyy.mp3"
  ],
  "status": "completed",
  "task_info": {
    "can_cancel": false
  },
  "type": "audio"
}

授权

​
Authorization
string
header
必填

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

获取 API Key ：

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

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

请求体

application/json
​
model
enum<string>
必填

模型名称

可选值：

  • suno-v4: V4版本，改进的人声质量，最长4分钟，prompt最多3000字符，style最多200字符
  • suno-v4.5: V4.5版本（推荐），更智能的提示词，更快的生成速度，最长8分钟，prompt最多5000字符，style最多1000字符
  • suno-v4.5plus: V4.5+增强版，音色更丰富，新的创作方式，最长8分钟，prompt最多5000字符，style最多1000字符
  • suno-v4.5all: V4.5全功能版，更智能的提示词，更快的生成速度，最长8分钟，prompt最多5000字符，style最多1000字符
  • suno-v5: V5最新版本，更卓越的音乐表现力，生成速度更快，prompt最多5000字符，style最多1000字符
可用选项:
suno-v4,
suno-v4.5,
suno-v4.5plus,
suno-v4.5all,
suno-v5
示例:

"suno-v4.5"

​
custom_mode
boolean
必填

是否开启自定义模式

说明：

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

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

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

false

​
instrumental
boolean
必填

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

说明：

  • 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
示例:

"pop, electronic, upbeat, female vocals"

​
title
string

歌曲标题

说明：

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

"夏日梦想"

​
negative_tags
string

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

示例：

  • heavy metal, screaming, sad
  • rap, fast tempo
示例:

"heavy metal, screaming"

​
vocal_gender
enum<string>

人声性别偏好

可选值：

  • m: 男声
  • f: 女声

注意：

  • 仅在custom_mode=true时生效
  • 此参数只能加强概率，不能保证一定遵循指定性别
可用选项:
m,
f
示例:

"f"

​
style_weight
number

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

取值范围： 0.0 ~ 1.0，保留一位小数

说明：

  • 值越高，生成结果越接近指定风格
  • 值为0时视为未设置
必填范围: 0 <= x <= 1
示例:

0.7

​
weirdness_constraint
number

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

取值范围： 0.0 ~ 1.0，保留一位小数

说明：

  • 值越高，生成结果越具有创意和实验性
  • 值越低，生成结果越传统和保守
  • 值为0时视为未设置
必填范围: 0 <= x <= 1
示例:

0.3

​
audio_weight
number

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

取值范围： 0.0 ~ 1.0，保留一位小数

说明：

  • 值为0时视为未设置
必填范围: 0 <= x <= 1
示例:

0.5

​
callback_url
string<uri>

任务完成后的HTTPS回调地址

回调时机：

  • 回调过程分三个阶段：text（文本生成）、first（第一首完成）、complete（全部完成）
  • 某些情况下可能跳过text和first阶段，直接返回complete

安全限制：

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

回调机制：

  • 超时时间：10秒
  • 失败后最多重试3次
  • 回调地址返回2xx状态码视为成功
示例:

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

响应

音乐任务创建成功

​
created
integer

任务创建时间戳

示例:

1766319090

​
id
string

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

示例:

"task-unified-1766319089-oqs9cue4"

​
model
string

实际使用的模型名称

示例:

"suno-v5"

​
object
enum<string>

任务的具体类型

可用选项:
audio.generation.task
​
progress
integer

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

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

100

​
result_data
object[]

生成的音乐详情数组，任务完成后返回

​
results
string<uri>[]

生成的音频URL数组，任务完成后返回

示例:
[
  "https://media.evolink.ai/xxx.mp3",
  "https://media.evolink.ai/yyy.mp3"
]
​
status
enum<string>

任务状态

可用选项:
pending,
processing,
completed,
failed
示例:

"completed"

​
task_info
object

音频任务详细信息

​
type
enum<string>

任务的输出类型

可用选项:
audio
示例:

"audio"