> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.
# 生成音乐
> 使用AI模型生成带或不带歌词的音乐。
### 使用指南
* 此接口根据您的文本提示创建音乐
* 每个请求会生成多个变体
* 您可以通过自定义模式和纯音乐设置来控制细节级别
### 参数详情
* 自定义模式下（`customMode: true`）:
* 如果 `instrumental: true`：需提供 `style` 和 `title`
* 如果 `instrumental: false`：需提供 `style`、`prompt` 和 `title`
* 不同模型的字符限制：
* **V4**：`prompt` 3000字符，`style` 200字符
* **V4\_5、V4\_5PLUS、V5、V5\_5 和 V4\_5ALL**：`prompt` 5000 字符，`style` 1000 字符（**V5\_5**：释放你的声音：定制模型，贴合你的独特品味 — 与 **V5** 字数限制一致）
* `title` 长度限制：80字符（所有模型）
* 非自定义模式下（`customMode: false`）:
* 无论 `instrumental` 设置如何，仅需提供 `prompt`
* `prompt` 长度限制：500字符
* 其他参数应留空
### 可选参数
以下字段为可选控制项：
* vocalGender（string）：偏好人声性别。允许值：`m`（男）、`f`（女）
* styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
* weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
* audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
* personaId（string）：自定义模式下可传入 Persona ID 或 Suno Voice 生成的 `voiceId`。如果使用 Voice 生成的 ID，`personaModel` 必须设置为 `voice_persona`。
* personaModel（string）：Persona 类型。生成 Persona 接口返回的 ID 使用 `style_persona`，Suno Voice 生成的 ID 使用 `voice_persona`。
```json 请求示例 theme={null}
{
"customMode": false,
"instrumental": false,
"prompt": "一段慵懒的 lo-fi 节奏并带柔和人声",
"model": "V4_5ALL",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
```
### 开发者注意事项
* 新用户建议：以 `customMode: false` 开始使用，更简单
* 生成的文件将保留14天
* 回调过程分三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate
openapi: 3.0.0
info:
title: intro
description: 这是生成音频的API接口文档
version: 1.0.0
contact:
name: 技术支持
email: support@api.box
servers:
- url: https://apibox.erweima.ai
description: API 服务器
security:
- BearerAuth: []
tags:
- name: Music Generation
description: 用于创建和管理音乐生成任务的接口
- name: Lyrics Generation
description: 用于歌词生成和管理的接口
- name: WAV Conversion
description: 用于将音乐转换为WAV格式的接口
- name: Vocal Removal
description: 用于从音乐轨道中移除人声的接口
- name: Music Video Generation
description: 用于生成MP4视频的接口
- name: Account Management
description: 用于账户和积分管理的接口
- name: Audio Enhancement
description: 用于增强和修改现有音频的伴奏和人声元素的接口
paths:
/api/v1/generate:
post:
summary: 生成音乐
operationId: generate-music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customMode
- instrumental
- callBackUrl
- model
properties:
prompt:
type: string
description: >-
描述所需音频内容的提示词。
- 自定义模式下（`customMode: true`）：当 `instrumental` 为 `false`
时必填。提示词将严格作为歌词使用并在生成的音轨中演唱。不同模型的字符限制：
- **V4**：最多3000字符
- **V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL**：最多5000字符
示例："一段平静舒缓的钢琴曲，带有柔和的旋律"
- 非自定义模式下（`customMode:
false`）：始终必填。提示词作为核心创意，歌词将根据它自动生成（不严格匹配输入）。最大长度：500字符。
示例："一段简短放松的钢琴曲"
example: 一段平静舒缓的钢琴曲，带有柔和的旋律
style:
type: string
description: |-
音乐风格或流派。
- 在自定义模式下（`customMode: true`）必填。示例："爵士"、"古典"、"电子"。
- 对于 V4 模型：最大长度为 200 字符。
- 对于 V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL 模型：最大长度为 1000 字符。
示例："古典"
- 在非自定义模式下（`customMode: false`）：留空。
example: 古典
title:
type: string
description: |-
生成音乐的标题。
- 在自定义模式下（`customMode: true`）必填。不同模型的字符限制：
- **V4和V4_5ALL**：最大长度80字符
- **V4_5、V4_5PLUS、V5、V5_5**：最大长度100字符
示例："宁静钢琴冥想"
- 在非自定义模式下（`customMode: false`）：留空。
example: 宁静钢琴冥想
customMode:
type: boolean
description: >-
启用自定义模式进行高级音频生成设置。
- 设为 `true` 使用自定义模式（需要提供 `style` 和 `title`；如果 `instrumental`
为 `false`，则需要提供 `prompt`）。如果 `instrumental` 为
`false`，提示词将严格用作歌词。
- 设为 `false` 使用非自定义模式（只需要提供 `prompt`）。歌词将根据提示词自动生成。
example: true
instrumental:
type: boolean
description: >-
决定音频是否为纯音乐（无歌词）。
- 在自定义模式下（`customMode: true`）：
- 如果为 `true`：只需提供 `style` 和 `title`。
- 如果为 `false`：需要提供 `style`、`title` 和 `prompt`（`prompt` 将作为精确歌词使用）。
- 在非自定义模式下（`customMode: false`）：不影响必填字段（只需 `prompt`）。如果为
`false`，将自动生成歌词。
example: true
personaId:
type: string
description: >-
仅在开启自定义参数时可用。应用到生成音乐的 Persona ID，可选。你可以传入以下两类 ID：
- 通过 [生成
Persona](https://docs.api.box/cn/suno-api/generate-persona)
接口生成的 Persona ID。此时可使用 `personaModel: style_persona`，或省略
`personaModel` 使用默认值。
- 通过 [Suno
Voice](https://docs.api.box/cn/suno-api/suno-voice-generate)
流程生成的 `voiceId`。当使用 Voice 生成的 ID 时，必须设置 `personaModel:
voice_persona`。
example: persona_123
personaModel:
type: string
description: >-
使用 `personaId` 时应用的 Persona 模型类型，可选。
- `style_persona`（默认）：用于生成 Persona 接口返回的 Persona ID。
- `voice_persona`：当 `personaId` 使用 Suno Voice 生成的 `voiceId`
时必须选择该值。该选项仅在 V5 与 V5_5 模型下可用。
enum:
- style_persona
- voice_persona
default: style_persona
example: style_persona
model:
type: string
description: |-
用于生成的AI模型版本。
- 所有请求都必填。
- 可用选项：
- **`V5`**：更卓越的音乐表现力，生成速度更快。
- **`V5_5`**：释放你的声音：定制模型，贴合你的独特品味。与 **V5** 的自定义模式下 `prompt`、`style` 字数上限一致（5000 / 1000）。
- **`V4_5PLUS`**：V4.5+ 的音色更丰富，新的创作方式，最长8分钟。
- **`V4_5`**：V4.5 更智能的提示词，更快的生成速度，最长8分钟。
- **`V4`**：V4 改进的人声质量，最长4分钟。
- **`V4_5ALL`**：V4.5-all 更好的歌曲结构，最长8分钟。
enum:
- V4_5ALL
- V4
- V4_5
- V4_5PLUS
- V5
- V5_5
example: V4_5ALL
negativeTags:
type: string
description: |-
需要在生成的音频中排除的音乐风格或特征。
- 可选。用于避免特定风格。
示例："重金属, 强节奏鼓点"
example: 重金属, 强节奏鼓点
callBackUrl:
type: string
format: uri
description: >-
接收任务完成通知的URL。回调过程有三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）。注意：某些情况下可能会跳过
`text` 和 `first` 阶段，直接返回 `complete`。
- 详细的回调格式和实现指南，请参见
[音乐生成回调](https://docs.api.box/cn/suno-api/generate-music-callbacks)
- 或者，您也可以使用获取音乐生成详情接口来轮询任务状态
example: https://api.example.com/callback
vocalGender:
type: string
description: 偏好人声性别。可选。允许值：'m'（男）、'f'（女）
enum:
- m
- f
example: m
styleWeight:
type: number
description: 风格贴合权重。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: 创造性/新颖度约束。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: 音频一致性与其他控制项的相对权重。可选。范围：0-1。建议保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: 任务ID，用于后续查询任务状态
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: |-
当音频生成完成时，系统会调用此回调通知结果。
### 回调示例
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "8551****662c",
"audio_url": "https://example.cn/****.mp3",
"source_audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"source_stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"source_image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] 夜晚城市 灯火辉煌",
"model_name": "chirp-v3-5",
"title": "钢铁侠",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
},
{
"id": "bd15****1873",
"audio_url": "https://example.cn/****.mp3",
"source_audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"source_stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"source_image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] 夜晚城市 灯火辉煌",
"model_name": "chirp-v3-5",
"title": "钢铁侠",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 228.28
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 状态码
example: 200
msg:
type: string
description: 返回消息
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
回调类型：text（文本生成完成）、first（第一首生成完成）、complete（全部生成完成）
enum:
- text
- first
- complete
task_id:
type: string
description: 任务ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: 音频唯一标识
audio_url:
type: string
description: 音频文件URL
source_audio_url:
type: string
description: 原始音频文件URL
stream_audio_url:
type: string
description: 流式音频URL
source_stream_audio_url:
type: string
description: 原始流式音频URL
image_url:
type: string
description: 封面图片URL
source_image_url:
type: string
description: 原始封面图片URL
prompt:
type: string
description: 生成提示词/歌词
model_name:
type: string
description: 使用的模型名称
title:
type: string
description: 音乐标题
tags:
type: string
description: 音乐标签
createTime:
type: string
description: 创建时间
format: date-time
duration:
type: number
description: 音频时长（秒）
responses:
'200':
description: 回调接收成功
method: post
type: path
path: '{request.body#/callBackUrl}'
components:
schemas:
ApiResponse:
type: object
properties:
code:
type: integer
description: |-
# 状态码说明
- ✅ 200 - 请求成功
- ⚠️ 400 - 参数错误
- ⚠️ 401 - 没有访问权限
- ⚠️ 404 - 请求方式或者路径错误
- ⚠️ 405 - 调用超过限制
- ⚠️ 413 - 主题或者prompt过长
- ⚠️ 429 - 积分不足
- ⚠️ 430 - 您的调用频率过高。请稍后再试。
- ⚠️ 455 - 网站维护
- ❌ 500 - 服务器异常
example: 200
enum:
- 200
- 400
- 401
- 404
- 405
- 413
- 429
- 430
- 455
- 500
msg:
type: string
description: 当 code != 200 时，展示错误信息
example: success
responses:
Error:
description: 服务器异常
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: |-
# 🔑 API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
## 获取 API Key
1. 访问 [API Key 管理页面](https://api.box/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **⚠️ 注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````