> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 生成音乐
> 使用AI模型生成带或不带歌词的音乐。
### 模型版本
* **当前模型**：`V6`（默认）、`V6_WILD`、`V6_MINI`
* **已废弃模型**：`V5_5`、`V5`、`V4_5PLUS`、`V4_5ALL`、`V4_5`、`V4`
* 废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。
### 使用指南
* 此接口根据您的文本提示创建音乐
* 每个请求会生成多个变体
* 您可以通过自定义模式和纯音乐设置来控制细节级别
### 参数详情
* 始终必填：`customMode`、`instrumental`、`model`
* 自定义模式下（`customMode: true`）:
* `title` 可选，最多 80 字符。仅此模式可用；`customMode` 为 `false` 时不支持
* `prompt` 可选；提供时将严格作为歌词使用并在生成的音轨中演唱。若同时传入 `lyrics`，优先使用 `lyrics` 作为歌词
* `style`、`lyrics`、`negativeTags` 至少提供一项，全部为空时将拒绝生成
* 如果 `instrumental: true`：生成纯音乐（无歌词）
* 如果 `instrumental: false`：使用 `lyrics`（未传则回退到 `prompt`）作为歌词
* `negativeTags`、`vocalGender`、`duration` 仅此模式可用。`customMode` 为 `false` 时请勿传入
* 可选：`duration`（10–360 秒）、`negativeTags`（V6 最多 1000 字符）、`vocalGender`（`m` / `f`）、`styleWeight`、`weirdnessConstraint`、`audioWeight`、`variety`、`personaId`、`personaModel`
* 不同模型的字符限制：
* **V4（已废弃）**：`prompt` 3000 字符，`style` 200 字符
* **V4\_5、V4\_5PLUS、V4\_5ALL、V5、V5\_5（已废弃）**：`prompt` 5000 字符，`style` 1000 字符
* **V6、V6\_MINI、V6\_WILD**：`style` 1000 字符；`lyrics` 5000 字符；`negativeTags` 1000 字符
* `title` 长度限制：80 字符（所有模型）
* 非自定义模式下（`customMode: false`）:
* `prompt` 可选；作为核心创意，歌词将根据它自动生成（不严格匹配输入），最多 3000 字符
* `lyrics` 可作为歌词附件，与 `prompt` 同时使用
* `imageUrls`、`videoUrls`、`audioUrls`、`style`、`lyrics` 至少提供一项，全部为空时将拒绝生成
* `imageUrls`、`videoUrls`、`audioUrls` 仅在此模式下有效
* 请勿传入仅自定义模式可用的参数：`title`、`negativeTags`、`duration`、`vocalGender`、`styleWeight`、`weirdnessConstraint`、`audioWeight`、`variety`、`personaId`、`personaModel`
* 附件总数不超过 10：`style` + `lyrics` + `imageUrls` + `videoUrls` + `audioUrls`
### 可选参数
以下字段为可选控制项：
* prompt（string）：描述所需音频内容的提示词。可选。自定义模式下作为歌词；非自定义模式下作为核心创意（最多 3000 字符）。
* lyrics（string）：歌词内容。可选。V6 系列最多 5000 字符。自定义模式优先于 `prompt` 作为歌词；非自定义模式可作为歌词附件与 `prompt` 同时使用。
* imageUrls（array）：图片参考。仅在 `customMode` 为 `false` 时有效。最多 5 张，单张不超过 10 MB，支持 jpeg、png、webp、bmp。
* videoUrls（array）：视频参考。仅在 `customMode` 为 `false` 时有效。最多 1 个，单个不超过 100 MB，时长不超过 241 秒，支持 mp4、mov、webm。
* audioUrls（array）：音频参考。仅在 `customMode` 为 `false` 时有效。时长需在 6 秒至 30 分钟之间，单个不超过 500 MB。
* style（string）：音乐风格规范。字符限制见上方「参数详情」。
* title（string）：曲目标题。可选。仅当 `customMode` 为 `true` 时可用。最多 80 字符。将显示在播放器界面和文件名中。
* negativeTags（string）：从生成音频中排除的音乐风格或特征。仅当 `customMode` 为 `true` 时可用。V6、V6\_MINI、V6\_WILD 最多 1000 字符。
* vocalGender（string）：人声性别偏好。`m` 男声，`f` 女声。仅当 `customMode` 为 `true` 时可用。根据实践，此参数只能加强概率，但不能保证一定遵循男女声的指令。
* styleWeight（number）：对指定风格的遵循强度。范围 0–1，保留两位小数。仅在 `customMode` 为 `true` 时有效。
* weirdnessConstraint（number）：创意/离散程度。范围 0–1，保留两位小数。仅在 `customMode` 为 `true` 时有效。
* audioWeight（number）：音频要素相对权重。范围 0–1，保留两位小数。仅在 `customMode` 为 `true` 时有效。
* variety（number）：生成结果的多样性。范围 0–4 的整数，默认 1。仅在 `customMode` 为 `true` 时有效。`0` off（严格同一风格），`1` normal（默认，平衡），`2` high（风格差异明显），`3` extra（大胆探索），`4` max（最大差异）。
* personaId（string）：Persona ID 或 Voice ID。可选。要生成 Persona ID，请访问 [生成 Persona](/cn/suno-api/generate-persona) 接口。
* personaModel（string）：persona 模型，可选 `style_persona` 或 `voice_persona`。仅 `V5`（已废弃）、`V5_5`（已废弃）、`V6`、`V6_MINI`、`V6_WILD` 可用。
* duration（number）：音频时长，单位为秒。范围 10–360，默认 20。仅当 `customMode` 为 `true` 时可用，且仅对 `V5_5`、`V6`、`V6_MINI`、`V6_WILD` 生效。
```json 非自定义模式 theme={null}
{
"customMode": false,
"instrumental": false,
"prompt": "一段慵懒的 lo-fi 节奏并带柔和人声",
"lyrics": "[Verse] 夜晚城市 灯火辉煌",
"style": "lo-fi, chill",
"imageUrls": [
"https://example.com/reference-image.png"
],
"videoUrls": [
"https://example.com/reference-video.mp4"
],
"audioUrls": [
"https://example.com/reference-audio.mp3"
],
"model": "V6",
"callBackUrl": "https://example.com/callback"
}
```
```json 自定义模式 theme={null}
{
"customMode": true,
"instrumental": false,
"title": "宁静钢琴冥想",
"style": "Classical",
"lyrics": "[Verse] 夜晚城市 灯火辉煌",
"prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律",
"negativeTags": "重金属, 快节奏鼓点",
"vocalGender": "m",
"styleWeight": 0.65,
"weirdnessConstraint": 0.65,
"audioWeight": 0.65,
"variety": 1,
"duration": 20,
"model": "V6",
"callBackUrl": "https://example.com/callback"
}
```
### 开发者注意事项
* 新用户建议：以 `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: 生成音乐
description: 使用AI模型生成带或不带歌词的音乐。
operationId: generate-music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customMode
- instrumental
- callBackUrl
- model
properties:
prompt:
type: string
description: >-
描述所需音频内容的提示词。可选。
- 自定义模式（`customMode: true`）：当提供 prompt
时，提示词将严格作为歌词使用并在生成的音轨中演唱。若同时传入 `lyrics`，优先使用 `lyrics`
作为歌词。不同模型的字符限制：
- **V4（已废弃）**：最多 3000 字符
- **V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）**：最多 5000 字符
- 非自定义模式（`customMode: false`）：当提供 prompt
时，提示词作为核心创意，歌词将根据提示词自动生成，不严格匹配输入，最多 3000 字符。
生成时无需强制填写 prompt，但非自定义模式下
`imageUrls`、`videoUrls`、`audioUrls`、`style`、`lyrics`
至少提供一项；自定义模式下 `style`、`lyrics`、`negativeTags`
至少提供一项。所有相关输入均为空时将拒绝生成。
example: 一段平静舒缓的钢琴曲，带有柔和的旋律
lyrics:
type: string
description: >-
歌词内容。可选。
- **V6、V6_MINI、V6_WILD**：最多 5000 字符。
- 自定义模式（`customMode: true`）时优先使用 `lyrics` 作为歌词；未传入 `lyrics`
时使用 `prompt` 作为歌词。
- 非自定义模式（`customMode: false`）时，`lyrics` 作为歌词附件，可与 `prompt`
中的音频描述同时使用。
example: '[Verse] 夜晚城市 灯火辉煌'
imageUrls:
type: array
description: >-
图片参考。仅在 `customMode` 为 `false` 时有效。
- 可选
- 最多上传 5 张图片；单张图片大小不超过 10 MB
- 支持 `jpeg`、`png`、`webp` 和 `bmp` 格式
- 非自定义模式下，附件总数不超过 10：`style` + `lyrics` + `imageUrls` +
`videoUrls` + `audioUrls`
items:
type: string
maxItems: 5
example:
- https://example.com/reference-image.png
videoUrls:
type: array
description: |-
视频参考。仅在 `customMode` 为 `false` 时有效。
- 可选
- 最多上传 1 个视频文件；单个文件大小不超过 100 MB，时长不超过 241 秒且无最短时长限制
- 支持 mp4、mov 和 webm 格式
items:
type: string
maxItems: 1
example:
- https://example.com/reference-video.mp4
audioUrls:
type: array
description: |-
音频参考。仅在 `customMode` 为 `false` 时有效。
- 可选
- 音频时长需在 6 秒至 30 分钟之间，单个音频文件大小不超过 500 MB
items:
type: string
example:
- https://example.com/reference-audio.mp3
style:
type: string
description: >-
生成音频的音乐风格规范。
- 不同模型的字符限制：
- **V4（已废弃）**：最多 200 字符
- **V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）**：最多 1000 字符
- **V6、V6_MINI、V6_WILD**：最多 1000 字符
- 常见示例：爵士乐、古典乐、电子乐、流行乐、摇滚乐、嘻哈等。
- 自定义模式下与 `lyrics`、`negativeTags` 至少提供一项；非自定义模式下与
`imageUrls`、`videoUrls`、`audioUrls`、`lyrics` 至少提供一项。
example: Classical
title:
type: string
description: >-
生成音乐曲目的标题。可选。
- 仅当 `customMode` 为 `true` 时可用。`customMode` 为 `false`
时不支持该字段。
- 最多 80 字符。
- 将显示在播放器界面和文件名中。
maxLength: 80
example: 宁静钢琴冥想
customMode:
type: boolean
description: |-
确定是否启用高级参数自定义。
- 如果为 `true`：允许详细控制
- 如果为 `false`：简化模式
example: true
instrumental:
type: boolean
description: |-
确定音频是否为纯音乐（无歌词）。
- 在自定义模式（`customMode: true`）下：
- 如果为 `true`：生成纯音乐（无歌词）
- 如果为 `false`：使用 `lyrics`（未传则回退到 `prompt`）作为歌词
- 在非自定义模式（`customMode: false`）下：
- 如果为 `true`：生成纯音乐（无歌词）
- 如果为 `false`：`lyrics` 可作为歌词附件，可与 `prompt` 中的音频描述同时使用
example: true
model:
type: string
description: |-
用于生成的 AI 模型版本。所有请求都必填。默认值：`V6`。可用选项：
- **`V6_WILD`**：突破风格边界，带来更大胆、更独特的音乐表达。
- **`V6_MINI`**：轻量快速，兼顾音质与效率，灵感创作更简单。
- **`V6`**：更强的音乐表现力，更自然的人声与丰富细节。推荐默认使用。
- **`V5_5`（已废弃）**：量身定制的专属模型，贴合您的独特品味。
- **`V5`（已废弃）**：更卓越的音乐表现力，生成速度更快。
- **`V4_5PLUS`（已废弃）**：V4.5+ 的音色更丰富，新的创作方式，最长 8 分钟。
- **`V4_5`（已废弃）**：V4.5 更智能的提示词，更快的生成速度，最长 8 分钟。
- **`V4_5ALL`（已废弃）**：V4.5ALL 更智能的提示词，更快的生成速度，最长 8 分钟。
- **`V4`（已废弃）**：V4 改进的人声质量，最长 4 分钟。
废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。
enum:
- V6
- V6_WILD
- V6_MINI
- V5_5
- V5
- V4_5PLUS
- V4_5ALL
- V4_5
- V4
example: V6
default: V6
callBackUrl:
type: string
format: uri
description: >-
接收任务完成通知的URL。回调过程有三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）。注意：某些情况下可能会跳过
`text` 和 `first` 阶段，直接返回 `complete`。
- 详细的回调格式和实现指南，请参见
[音乐生成回调](https://docs.sunoapi.org/cn/suno-api/generate-music-callbacks)
- 或者，您也可以使用获取音乐生成详情接口来轮询任务状态
example: https://api.example.com/callback
negativeTags:
type: string
description: |-
从生成的音频中排除的音乐风格或特征。可选。
- 仅当 `customMode` 为 `true` 时可用。`customMode` 为 `false` 时请勿传入。
- V6、V6_MINI、V6_WILD 最多 1000 字符。
- 自定义模式下与 `style`、`lyrics` 至少提供一项。
maxLength: 1000
example: 重金属, 快节奏鼓点
vocalGender:
type: string
description: |-
人声性别偏好。可选。
- 仅当 `customMode` 为 `true` 时可用。`customMode` 为 `false` 时请勿传入。
- `m` 表示男声，`f` 表示女声。
- 根据实践，此参数只能加强概率，但不能保证一定遵循男女声的指令。
enum:
- m
- f
example: m
styleWeight:
type: number
description: >-
仅当启用自定义模式（`customMode: true`）时可用。对指定风格的遵循强度。可选。范围
0–1，保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: >-
仅当启用自定义模式（`customMode: true`）时可用。控制实验性/创意偏离程度。可选。范围
0–1，保留两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: |-
仅当启用自定义模式（`customMode: true`）时可用。音频要素相对权重。可选。范围 0–1，保留两位小数。
- 无人声时不支持 `audioWeight`
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
variety:
type: number
description: >-
仅当启用自定义模式（`customMode: true`）时可用。控制生成结果的多样性和风格差异程度。可选。范围
0–4，取整数，默认值为 1。
- **`0`**：off（exact style），完全关闭，严格用同一风格
- **`1`**：normal（balanced variety），默认值，在稳定性和多样性之间保持平衡
- **`2`**：high（distinct styles），生成风格差异明显的结果
- **`3`**：extra（bold exploration），提供更高程度的变化，鼓励大胆探索不同风格
- **`4`**：max（unreasonably
varied），最大程度增加多样性，生成结果可能具有非常明显的风格差异
minimum: 0
maximum: 4
multipleOf: 1
default: 1
example: 1
personaId:
type: string
description: >-
用于应用于生成音乐的 Persona ID 或 Voice ID。可选。仅在 `customMode` 为 `true`
时有效。使用此选项可将特定的 Persona 风格应用于您的音乐生成。
要生成 Persona ID，请使用 [生成
Persona](https://docs.sunoapi.org/cn/suno-api/generate-persona)
端点，基于生成的音乐创建个性化的音乐 Persona。
要生成 Voice ID，请使用 [生成
Voice](https://docs.sunoapi.org/cn/suno-api/suno-voice-generate)
端点。当使用 Voice 生成的 ID 时，必须设置 `personaModel: voice_persona`。
example: persona_123
personaModel:
type: string
description: >-
persona 模型，可选 `style_persona` 或 `voice_persona`。仅
`V5`（已废弃）、`V5_5`（已废弃）、`V6`、`V6_MINI`、`V6_WILD` 可用。仅在
`customMode` 为 `true` 时有效。
- `style_persona`（默认）：用于生成 Persona 接口返回的 Persona ID。
- `voice_persona`：当 `personaId` 使用 Suno Voice 生成的 `voiceId`
时必须选择该值。
enum:
- style_persona
- voice_persona
default: style_persona
example: style_persona
duration:
type: number
description: |-
音频时长，单位为秒。可选。
- 仅当 `customMode` 为 `true` 时可用。`customMode` 为 `false` 时请勿传入。
- 范围 10–360 秒，默认 20。
- 仅当 `model` 为 `V5_5`（已废弃）、`V6`、`V6_MINI`、`V6_WILD` 时有效。
minimum: 10
maximum: 360
default: 20
example: 20
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
deprecated: true
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 泄露，请立即在管理页面重置
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.