> ## 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.
# 生成混音
> 通过混合两个音频文件来创建混音，生成新的音乐。
### 使用指南
* 此接口用于通过组合两个音频文件来创建混音
* uploadUrlList 数组中必须包含恰好 2 个音频文件 URL
* 支持自定义和非自定义模式，适用于不同的生成风格
* 生成的混音可用于创建 Persona，用于后续的音乐生成
### 参数详情
* `uploadUrlList`: 必需参数，包含恰好 2 个音频文件 URL 的数组，用于混合生成混音。两个 URL 必须有效且可访问。
* `customMode`: 必需参数，启用自定义模式以进行高级音频生成设置
* `prompt`: 必需。字符限制按模型：
* **V4**: 自定义模式最多 3000 字符，非自定义模式最多 500 字符
* **V4\_5, V4\_5PLUS, V4\_5ALL & V5**: 自定义模式最多 5000 字符，非自定义模式最多 500 字符
* `style`: 在自定义模式下必需。字符限制按模型：
* **V4**: 最多 200 字符
* **V4\_5, V4\_5PLUS, V4\_5ALL & V5**: 最多 1000 字符
* `title`: 在自定义模式下必需。字符限制按模型：
* **V4 & V4\_5ALL**: 最多 80 字符
* **V4\_5, V4\_5PLUS & V5**: 最多 100 字符
* `instrumental`: 确定音频是否应为纯音乐（无歌词）
* `model`: 必需参数，用于音频生成的模型版本
* `vocalGender`: 可选参数，生成人声的性别偏好（m 或 f）
* `styleWeight`: 可选参数，提供的风格指导权重（0.00–1.00）
* `weirdnessConstraint`: 可选参数，创意偏差/新颖性约束（0.00–1.00）
* `audioWeight`: 可选参数，输入音频影响的权重（0.00–1.00）
* `callBackUrl`: 必需参数，接收任务完成通知的 URL
### 开发者注意事项
1. **音频要求**：确保 uploadUrlList 中的两个音频文件都可访问且有效。系统将混合这两个音频文件以创建混音。
2. **生成的文件**：生成的文件将保留15天后删除
3. **确保所有必需字段**：请根据 customMode 和 instrumental 设置提供所有必需参数，避免出错
4. **字符限制**：请注意 prompt、style 和 title 的字符长度限制，确保成功处理
5. **回调过程**：回调过程有三个阶段：text（文本生成完成）、first（第一首完成）、complete（全部完成）
6. **任务状态**：您可以使用音乐生成详情查询接口主动检查任务状态，而不必等待回调
7. **Persona 生成**：生成的混音可用于生成 Persona 接口，为后续的音乐生成创建 Persona
### 参数示例
```json 自定义模式（纯音乐） theme={null}
{
"uploadUrlList": [
"https://storage.example.com/audio1.mp3",
"https://storage.example.com/audio2.mp3"
],
"customMode": true,
"instrumental": true,
"style": "电子舞曲",
"title": "混音组合",
"model": "V4_5ALL",
"callBackUrl": "https://api.example.com/callback"
}
```
```json 自定义模式（带人声） theme={null}
{
"uploadUrlList": [
"https://storage.example.com/audio1.mp3",
"https://storage.example.com/audio2.mp3"
],
"customMode": true,
"instrumental": false,
"prompt": "[Verse] 融合两个世界，创造新的事物",
"style": "电子流行",
"title": "融合混音",
"model": "V5",
"vocalGender": "f",
"styleWeight": 0.7,
"callBackUrl": "https://api.example.com/callback"
}
```
```json 非自定义模式 theme={null}
{
"uploadUrlList": [
"https://storage.example.com/audio1.mp3",
"https://storage.example.com/audio2.mp3"
],
"customMode": false,
"prompt": "一个结合两种不同音乐风格的动态混音",
"model": "V4_5ALL",
"callBackUrl": "https://api.example.com/callback"
}
```
确保 uploadUrlList 中的两个音频文件 URL 都可访问且有效。系统需要恰好 2 个 URL 来创建混音。
为了获得最佳效果，使用具有相似特征（节拍、调性等）的音频文件来创建更和谐的混音。您也可以使用生成的混音来创建 Persona，用于后续的音乐生成。
uploadUrlList 必须包含恰好 2 个音频文件 URL。提供更多或更少的 URL 将导致错误。
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/mashup
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/mashup:
post:
summary: 生成混音音乐
operationId: generate-mashup
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrlList
- customMode
- callBackUrl
- model
properties:
uploadUrlList:
type: array
description: 要混音的音频文件URL数组。必须包含恰好2个URL。每个URL必须是可公开访问的。
items:
type: string
format: uri
minItems: 2
maxItems: 2
example:
- https://example.com/audio1.mp3
- https://example.com/audio2.mp3
prompt:
type: string
description: >-
描述所需音频内容的提示词。
- 自定义模式下（`customMode:
true`）：必填。提示词将严格作为歌词使用并在生成的音轨中演唱。不同模型的字符限制：
- **V4**：最多3000字符
- **V4_5 和 V4_5PLUS**：最多5000字符
- **V4_5ALL**：最多5000字符
- **V5**：最多5000字符
示例："一段平静舒缓的钢琴曲，带有柔和的旋律"
- 非自定义模式下（`customMode:
false`）：始终必填。提示词作为核心创意，歌词将根据它自动生成（不严格匹配输入），最多500字符。
示例："一段简短放松的钢琴曲"
example: A calm and relaxing piano track with soft melodies
style:
type: string
description: |-
生成音频的音乐风格规范。
- 仅在自定义模式（`customMode: true`）下可用且必填。定义流派、情绪或艺术方向。
- 不同模型的字符限制：
- **V4**：最多200字符
- **V4_5 和 V4_5PLUS**：最多1000字符
- **V4_5ALL**：最多1000字符
- **V5**：最多1000字符
- 常见示例：爵士乐、古典乐、电子乐、流行乐、摇滚乐、嘻哈等。
example: Jazz
title:
type: string
description: |-
生成音乐曲目的标题。
- 仅在自定义模式（`customMode: true`）下可用且必填。
- 最大长度：80字符。
- 将显示在播放器界面和文件名中。
example: Relaxing Piano
customMode:
type: boolean
description: |-
确定是否启用高级参数自定义。
- 如果为 `true`：允许详细控制，对 `style` 和 `title` 字段有特定要求。
- 如果为 `false`：简化模式，只需要 `prompt`，其他参数将被忽略。
example: true
instrumental:
type: boolean
description: |-
确定音频是否为纯音乐（无歌词）。
- 仅在非自定义模式（`customMode: false`）下可用。
- 在自定义模式下此参数不可用。
example: true
model:
type: string
description: |-
用于生成的AI模型版本。
- 所有请求都必填。
- 可用选项：
- **`V5`**： 更卓越的音乐表现力，生成速度更快。
- **`V4_5PLUS`**：V4.5+ 的音色更丰富，新的创作方式，最长8分钟。
- **`V4_5`**：V4.5 更智能的提示词，更快的生成速度，最长8分钟。
- **`V4_5ALL`**：V4.5ALL 更智能的提示词，更快的生成速度，最长8分钟。
- **`V4`**：V4 改进的人声质量，最长4分钟。
enum:
- V4
- V4_5
- V4_5PLUS
- V4_5ALL
- V5
example: V4
callBackUrl:
type: string
format: uri
description: >-
用于接收音乐生成任务完成更新的URL地址。所有音乐生成请求都需要此参数。
- 系统将在音乐生成完成时向此URL发送POST请求，包含任务状态和结果
- 回调过程有三个阶段：`text`（文本生成）、`first`（第一个音轨完成）、`complete`（所有音轨完成）
- 注意：某些情况下可能会跳过 `text` 和 `first` 阶段，直接返回 `complete`
- 您的回调端点应能接受包含音乐生成结果的JSON载荷的POST请求
- 详细的回调格式和实现指南，请参见
[音乐生成回调](https://docs.sunoapi.org/cn/suno-api/generate-music-callbacks)
- 或者，您也可以使用获取音乐详情接口来轮询任务状态
example: https://example.com/callback
vocalGender:
type: string
description: >-
人声性别偏好。
- 仅在自定义模式（`customMode: true`）下可用。可选。使用 'm' 表示男声，'f'
表示女声。根据实践，此参数只能增加概率，但不能保证遵循男女声指令。
enum:
- m
- f
example: m
styleWeight:
type: number
description: |-
对指定风格的遵循强度。
- 仅在自定义模式（`customMode: true`）下可用。可选。范围 0–1，保留2位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.61
weirdnessConstraint:
type: number
description: |-
控制实验性/创意偏差。
- 仅在自定义模式（`customMode: true`）下可用。可选。范围 0–1，保留2位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.72
audioWeight:
type: number
description: |-
音频特征与其他因素的平衡权重。
- 仅在自定义模式（`customMode: true`）下可用。可选。范围 0–1，保留2位小数。
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: |-
响应状态码
- **200**: 成功 - 请求已成功处理
- **401**: 未授权 - 认证凭据缺失或无效
- **402**: 积分不足 - 账户没有足够的积分来执行此操作
- **404**: 未找到 - 请求的资源或端点不存在
- **409**: 冲突 - WAV记录已存在
- **422**: 验证错误 - 请求参数验证失败
- **429**: 速率限制 - 此资源的请求限制已超出
- **451**: 未授权 - 无法获取图像。请验证您或您的服务提供商设置的任何访问限制
- **455**: 服务不可用 - 系统正在进行维护
- **500**: 服务器错误 - 处理请求时发生意外错误
msg:
type: string
description: 当 code != 200 时的错误消息
example: success
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: >-
用于跟踪任务状态的任务ID。使用此ID通过
[获取音乐详情](/cn/suno-api/get-music-generation-details)
接口查询任务详情和结果。
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: |-
系统将在音频生成完成时调用此回调。
### 回调示例
```json
{
"code": 200,
"msg": "全部生成成功。",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "e231****-****-****-****-****8cadc7dc",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"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",
"stream_audio_url": "https://example.cn/****",
"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: 全部生成成功
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
stream_audio_url:
type: string
description: 流式音频URL
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: 回调接收成功
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: |-
响应状态码
- **200**: 成功 - 请求已成功处理
- **400**: 验证错误 - 歌词包含受版权保护的内容。
- **408**: 速率限制 - 超时。
- **413**: 冲突 - 上传的音频与现有艺术作品匹配。
- **500**: 服务器错误 - 处理请求时发生意外错误
- **501**: 音频生成失败。
- **531**: 服务器错误 - 抱歉，由于问题导致生成失败。您的积分已退还。请重试。
msg:
type: string
description: 当 code != 200 时的错误消息
example: success
example:
code: 200
msg: success
method: post
type: path
path: '{request.body#/callBackUrl}'
components:
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 泄露，请立即在管理页面重置
````