跳转到主要内容
POST
/
api
/
v1
/
generate
/
sounds
生成声音
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/sounds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "轻柔的雨声环境音，带有远处雷声和微风",
  "model": "V5",
  "soundLoop": false,
  "soundTempo": 120,
  "soundKey": "Any",
  "grabLyrics": false,
  "callBackUrl": "https://api.example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "a1b2****c3d4"
  }
}
用于创建声音生成任务（Sounds Task）。支持设置循环播放、节奏（BPM）、调性（Key）以及歌词字幕抓取等能力。

​
🚀 使用指南

  • 使用该接口可以基于输入的 prompt 生成对应的音频内容。
  • 支持设置循环播放效果，适用于背景音乐、环境音等场景。
  • 支持指定 BPM（每分钟节拍数）和 Key（调性），便于控制生成结果的风格。
  • 可选开启歌词字幕抓取，便于后续展示或处理歌词内容。
  • 支持通过回调地址异步接收任务完成通知。

​
📌 适用场景

  • 🎧 背景音乐创作
  • 🎮 游戏音效或循环环境声生成
  • 🌐 音频内容平台与创作工具集成

授权

​
Authorization
string
header
必填

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

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

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

⚠️ 注意：

  • 请妥善保管您的 API Key，不要泄露给他人
  • 如果怀疑 API Key 泄露，请立即在管理页面重置

请求体

application/json
​
prompt
string
必填

sounds 任务提示词，最多 500 字符。

Maximum string length: 500
示例:

"轻柔的雨声环境音，带有远处雷声和微风"

​
model
enum<string>
必填

模型名称。sounds 任务类型仅支持 V5。

可用选项:
V5
示例:

"V5"

​
soundLoop
boolean
默认值:false

是否循环播放。

示例:

false

​
soundTempo
integer | null

BPM（每分钟节拍数），不传则为 Auto。

必填范围: 1 <= x <= 300
示例:

120

​
soundKey
enum<string>
默认值:Any

Key（调性），默认 Any。

可用选项:
Any,
Cm,
C#m,
Dm,
D#m,
Em,
Fm,
F#m,
Gm,
G#m,
Am,
A#m,
Bm,
C,
C#,
D,
D#,
E,
F,
F#,
G,
G#,
A,
A#,
B
示例:

"Any"

​
grabLyrics
boolean

是否抓取歌词字幕。任务完成后可调用接口获取歌词字幕。

示例:

false

​
callBackUrl
string<uri>

回调地址，用于异步接收任务完成通知。

示例:

"https://api.example.com/callback"

响应

请求成功

​
code
enum<integer>

状态码说明

  • ✅ 200 - 请求成功
  • ⚠️ 400 - 参数错误
  • ⚠️ 401 - 没有访问权限
  • ⚠️ 404 - 请求方式或者路径错误
  • ⚠️ 405 - 调用超过限制
  • ⚠️ 413 - 主题或者prompt过长
  • ⚠️ 429 - 积分不足
  • ⚠️ 430 - 您的调用频率过高，请稍后再试。
  • ⚠️ 455 - 网站维护
  • ❌ 500 - 服务器异常
可用选项:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
示例:

200

​
msg
string

当 code != 200 时，展示错误信息

示例:

"success"

​
data
object