> ## 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生成的人声来增强乐器曲目，人声与您指定的风格和内容相匹配。
## 主要功能
* **人声增强**: 为现有乐器曲目添加人声
* **风格匹配**: 生成与上传音频风格和情绪匹配的人声
* **内容控制**: 指定人声风格、流派和特征
* **质量筛选**: 使用负面标签避免不需要的人声风格
### 参数使用指南
所有请求的必需参数：
* `uploadUrl`: 有效的乐器音频文件URL
* `prompt`: 所需人声内容和风格的描述
* `title`: 生成的人声曲目标题
* `style`: 音乐和人声风格（例如："爵士"、"流行"、"古典"）
* `negativeTags`: 要排除的人声风格或特征
* `callBackUrl`: 接收完成通知的URL
### 可选参数
通过以下参数微调人声生成：
* `vocalGender`: 首选人声性别（'m'表示男性，'f'表示女性）
* `styleWeight`: 风格指引权重（0.00-1.00）
* `weirdnessConstraint`: 创意/新颖性约束（0.00-1.00）
* `audioWeight`: 音频一致性权重（0.00-1.00）
* `model`：用于生成的模型版本。可选值：`V4_5PLUS`（默认）、`V5`、`V5_5`
## 音频要求
* **输入类型**: 乐器或背景音轨音频文件
* **文件格式**: MP3、WAV或其他支持的音频格式
* **质量**: 清晰的乐器曲目最适合人声添加
* **可访问性**: 确保上传的音频URL是公开可访问的
## 人声生成过程
1. **音频分析**: 系统分析上传的乐器曲目
2. **风格匹配**: 生成与音乐风格互补的人声
3. **内容创建**: 基于您的提示和风格参数创建人声内容
4. **最终混音**: 将人声与原始乐器混合
## 响应信息
* **处理时间**: 通常需要2-4分钟，取决于曲目复杂性
* **回调阶段**: 可能发生多个回调阶段（text、first、complete）
* **输出**: 在原始乐器上添加人声的增强音频
## 开发者注意事项
1. **内容权利**: 确保您有使用上传音频的适当权利
2. **文件保留**: 生成的人声曲目保留15天
3. **输入质量**: 更高质量的乐器输入产生更好的人声效果
4. **风格一致性**: AI尝试使人声风格与乐器风格匹配
5. **处理时间**: 复杂的编排可能需要额外的处理时间
## 最佳实践
### 人声增强提示
* 使用清晰、混音良好的乐器曲目以获得最佳效果
* 在提示中具体说明人声风格（例如："流畅爵士人声"、"充满活力的流行人声"）
* 当您有偏好时指定人声性别
* 使用负面标签避免冲突的人声风格
### 重要考虑事项
* 系统在具有清晰旋律结构的乐器曲目上效果最佳
* 非常繁忙或密集的乐器编排可能影响人声清晰度
* 确保您的提示描述了所需的人声内容和情绪
* 在描述人声风格时考虑您乐器的调性和节拍
## 示例用例
* **音乐制作**: 为乐器作品添加人声
* **演示创建**: 从乐器草图创建人声演示
* **风格探索**: 在同一乐器上尝试不同的人声风格
* **内容创建**: 为多媒体项目生成人声内容
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/add-vocals
openapi: 3.0.0
info:
title: intro
description: 这是生成音频的API接口文档
version: 1.0.0
contact:
name: 技术支持
email: support@sunoapi.org
servers:
- url: https://api.sunoapi.org
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: 用于账户和积分管理的接口
paths:
/api/v1/generate/add-vocals:
post:
tags:
- Music Generation
summary: 添加人声
operationId: add-vocals
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- callBackUrl
- prompt
- title
- negativeTags
- style
properties:
prompt:
type: string
description: |-
要生成人声的音频内容描述。
- 必填。
- 提供关于所需人声风格和内容的上下文。
- 您的提示越详细，人声生成越符合您的设想。
example: 一段平静放松的钢琴曲配舒缓人声
title:
type: string
description: |-
音乐曲目的标题。
- 必填。
- 这将用作生成的人声曲目的标题。
example: 轻松钢琴配人声
negativeTags:
type: string
description: |-
要从生成的曲目中排除的音乐风格或人声特征。
- 必填。
- 用于避免特定的人声风格或特征。
示例："重金属, 激进人声"
example: 重金属, 激进人声
style:
type: string
description: |-
音乐和人声风格。
- 必填。
- 示例："爵士"、"古典"、"电子"、"流行"。
- 描述整体流派和人声方式。
example: 爵士
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.61
weirdnessConstraint:
type: number
description: 创意/新颖性约束。可选。范围：0-1。建议使用两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.72
audioWeight:
type: number
description: 音频一致性相对于其他控制的权重。可选。范围：0-1。建议使用两位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
uploadUrl:
type: string
format: uri
description: |-
要添加人声的上传音频文件的URL。
- 必填。
- 必须是系统可访问的有效音频文件URL。
- 上传的音频应为支持的格式（MP3、WAV等）。
example: https://example.com/instrumental.mp3
callBackUrl:
type: string
format: uri
description: >-
人声生成完成时接收任务完成通知的URL。回调过程有三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）。注意：某些情况下可能会跳过
`text` 和 `first` 阶段，直接返回 `complete`。
- 详细的回调格式和实现指南，请参见
[添加人声回调](https://docs.sunoapi.org/cn/suno-api/add-vocals-callbacks)
- 或者，您也可以使用获取音乐生成详情接口来轮询任务状态
example: https://api.example.com/callback
model:
type: string
description: 用于生成的模型版本。可选。默认值：V4_5PLUS。
enum:
- V4_5PLUS
- V5
- V5_5
default: V4_5PLUS
example: V4_5PLUS
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:
vocalsAdded:
'{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": "[副歌] 平静放松的旋律配上舒缓的人声",
"model_name": "chirp-v3-5",
"title": "轻松钢琴配人声",
"tags": "轻松, 钢琴, 人声, 爵士",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
}
]
}
}
```
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: 音频唯一标识符（audioId）
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://sunoapi.org/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **⚠️ 注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````