> ## 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.
# 添加乐器
通过上传音频文件生成现有音乐曲目的乐器版本。此接口允许您基于上传的音乐创建乐器伴奏。
## 主要功能
* **基于上传的处理**: 上传您现有的音乐文件以创建乐器版本
* **风格控制**: 定义所需的乐器风格和特征
* **质量筛选**: 使用负面标签排除不需要的风格或乐器
* **灵活参数**: 可选的人声性别、风格权重和音频权重控制
## 使用指南
### 必需参数
所有请求必须包含：
* `uploadUrl`: 有效的音频文件URL（MP3、WAV等）
* `title`: 生成的乐器曲目标题
* `tags`: 乐器所需的风格和特征
* `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访问
* **质量**: 更高质量的输入通常产生更好的乐器效果
## 响应信息
* **处理时间**: 通常需要2-4分钟，取决于音频长度和复杂性
* **回调阶段**: 系统可能在不同阶段调用您的回调URL（text、first、complete）
* **结果格式**: 返回用于下载和流式传输的音频URL
## 开发者注意事项
1. **文件保留**: 生成的乐器文件保留15天
2. **并发**: 遵守速率限制以避免请求被拒绝
3. **风格标签**: 使用具体的标签以获得所需的乐器风格
4. **负面标签**: 有效使用负面标签以避免不需要的元素
5. **回调处理**: 实施适当的回调处理以可靠地获取结果
## 最佳实践
### 优化提示
* 使用描述性和具体的风格标签（例如："原声吉他, 柔和钢琴, 环境音乐"）
* 包含相关的负面标签以排除不需要的元素
* 确保上传的音频URL是公开可访问且稳定的
* 首先使用较短的音频片段测试以了解系统行为
### 重要考虑事项
* 确保您有使用上传音频内容的适当权利
* 系统在清晰、高质量的音频输入下效果最佳
* 非常短的音频片段（少于10秒）可能产生有限的结果
* 复杂的多乐器曲目可能需要更多处理时间
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/add-instrumental
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-instrumental:
post:
tags:
- Music Generation
summary: 添加乐器
operationId: add-instrumental
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- title
- negativeTags
- tags
- callBackUrl
properties:
uploadUrl:
type: string
format: uri
description: |-
要添加乐器的上传音乐文件的URL。
- 必填。
- 必须是系统可访问的有效音频文件URL。
- 上传的音频应为支持的格式（MP3、WAV等）。
example: https://example.com/music.mp3
title:
type: string
description: |-
音乐曲目的标题。
- 必填。
- 这将用作生成的乐器曲目的标题。
example: 轻松钢琴
negativeTags:
type: string
description: |-
要从生成的乐器中排除的音乐风格或特征。
- 必填。
- 用于避免乐器版本中的特定风格或乐器。
示例："重金属, 激进鼓点"
example: 重金属, 激进鼓点
tags:
type: string
description: |-
乐器的音乐风格和特征。
- 必填。
- 描述乐器曲目所需的风格、情绪和乐器。
示例："轻松钢琴, 环境音乐, 宁静"
example: 轻松钢琴, 环境音乐, 宁静
callBackUrl:
type: string
format: uri
description: >-
乐器生成完成时接收任务完成通知的URL。回调过程有三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）。注意：某些情况下可能会跳过
`text` 和 `first` 阶段，直接返回 `complete`。
- 详细的回调格式和实现指南，请参见
[添加乐器回调](https://docs.sunoapi.org/cn/suno-api/add-instrumental-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.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
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:
instrumentalAdded:
'{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 泄露，请立即在管理页面重置
````