> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Suno API：音效生成
> 通过文本提示生成音效、环境音以及可循环音频。
### 重要说明
* 支持 `v5` 和 `v5.5`
* `prompt` 为必填项，应清晰描述目标音效
* `sound_loop` 可用于环境底噪、UI 音效及其他可循环播放的效果
* `sound_tempo` 与 `sound_key` 为可选参数，可用于更结构化的声音设计
* 当需要歌词风格字幕元数据时，可开启 `grab_lyrics`
### 使用场景
* 🔔 产品 / 应用提示音
* 🎮 游戏 / 互动场景环境循环音效
* 🎞️ 短视频 / 广告 / 视频转场音效
### 生成音效
通过文本提示创建非音乐类音频，例如环境音、冲击音、转场音、UI 音效以及可循环音效。
```json basic sound effect theme={null} theme={null}
{
"model": "suno/sounds-generate",
"callback_url": "",
"input": {
"model": "v5.5",
"prompt": "暴雨敲打汽车车顶，伴随远处雷声以及偶尔的雨刷摆动声。"
}
}
```
```json loopable ambience theme={null} theme={null}
{
"model": "suno/sounds-generate",
"callback_url": "",
"input": {
"model": "v5",
"prompt": "复古街机厅环境音，带有轻微机器嗡鸣声、投币声以及细微电子提示音。",
"sound_loop": true,
"sound_tempo": 110,
"sound_key": "Cm",
"grab_lyrics": false
}
}
```
### 获取任务结果
提交任务后，可通过统一查询接口查看任务进度并获取生成结果：
了解如何查询 Suno 任务状态并获取生成结果
## OpenAPI
````yaml zh/suno-api/sounds-generate.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
title: Crun Suno 音效生成 API
description: crun.ai Suno 音效生成 API 文档
version: 1.0.0
contact:
name: 技术支持
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务地址
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/CreateTask:
post:
summary: Suno 音效生成
operationId: suno/sounds-generate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- suno/sounds-generate
description: |-
用于生成的模型名称，为必填字段。
- 当前接口必须填写 `suno/sounds-generate`
callback_url:
type: string
format: uri
description: |-
可选。用于接收任务完成通知的回调地址。
- 当生成完成后，系统会通过 POST 请求将任务状态与结果发送到该地址
- 回调数据结构与任务状态查询接口中的 `data` 对象保持一致
- 你的回调接口应支持接收 JSON 格式 POST 请求
- 成功接收后应返回 HTTP 200 状态码
example: https://your-domain.com/api/callback
input:
$ref: '#/components/schemas/SunoSoundsGenerateInput'
example:
model: suno/sounds-generate
callback_url: https://your-domain.com/api/callback
input:
model: v5.5
prompt: 暴雨敲打汽车车顶，伴随远处雷声以及偶尔的雨刷摆动声。
sound_loop: false
sound_tempo: 120
sound_key: Cm
grab_lyrics: false
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，可通过获取任务详情接口查询任务状态
example: task_12345678
example:
code: 200
message: success
data:
task_id: task_12345678
'422':
description: 参数校验失败
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: 详细参数错误信息
items:
type: string
example:
- specific error field message
example:
code: 422
message: 缺少参数或参数类型错误
errors:
- specific error field message
'500':
$ref: '#/components/responses/Error'
components:
schemas:
SunoSoundsGenerateInput:
type: object
description: |-
Suno 音效生成输入参数。
规则说明：
- `model` 为必填，仅支持 `v5` 或 `v5.5`
- `prompt` 为必填，用于描述目标音效
- `sound_tempo` 为可选参数，取值范围为 1 到 300
- `sound_key` 为可选参数，支持常见的大调与小调音阶
properties:
model:
type: string
enum:
- v5
- v5.5
description: Suno 音效生成模型版本。
example: v5.5
prompt:
type: string
maxLength: 500
description: 用于描述目标音效、环境音或循环音效的提示词。
example: 暴雨敲打汽车车顶，伴随远处雷声以及偶尔的雨刷摆动声。
sound_loop:
type: boolean
description: 是否生成可无缝循环播放的音效。
default: false
example: false
sound_tempo:
type: integer
minimum: 1
maximum: 300
description: 可选的节奏提示，用于辅助生成更有结构感的音效。
example: 120
sound_key:
type: string
enum:
- 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
description: 可选参数，用于指定生成音效的音调。
example: Cm
grab_lyrics:
type: boolean
description: 当可用时，是否提取歌词风格字幕元数据。
default: false
example: false
required:
- model
- prompt
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
description: |-
响应状态码
- **200**：成功 - 请求已成功处理
- **401**：未授权 - 缺少认证信息或认证无效
- **402**：Credits 不足 - 账户余额不足以完成当前操作
- **404**：未找到 - 请求的资源或接口不存在
- **422**：参数校验失败 - 请求参数未通过校验
- **429**：请求频率受限 - 超出当前资源的请求限制
- **455**：服务不可用 - 系统当前正在维护中
- **500**：服务器错误 - 请求处理过程中发生未知错误
- **501**：生成失败 - 内容生成任务失败
- **505**：功能已禁用 - 当前请求的功能暂不可用
message:
type: string
description: 响应消息，请求失败时为错误描述
example: success
responses:
Error:
description: 服务器错误
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: |-
所有 API 均需通过 API Key 进行身份认证。
获取 API Key：
1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key
使用方式：
在请求头中添加：
x-api-key: YOUR_API_KEY
注意事项：
- 请妥善保管你的 API Key，不要泄露给他人
- 如果怀疑 API Key 已泄露，请立即在管理页面中重置
````