> ## 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模型将两个音频文件混合生成新的混音作品。
### 使用指南
* 此接口从最多2个上传的音频文件创建混音音乐
* 将多个轨道的元素组合成一个连贯的新作品
* 您可以通过自定义模式和纯音乐设置来控制细节级别
### 参数详情
* `uploadUrlList` 是必需的，必须包含恰好2个音频文件URL
* **model**（string，必填）：`V4`、`V4_5`、`V4_5PLUS`、`V4_5ALL`、`V5`、`V5_5`。**`V5_5`**：释放你的声音：定制模型，贴合你的独特品味 — 自定义模式下与 **`V5`** 字数限制一致。
* 自定义模式下（`customMode: true`）:
* 不同模型的`prompt`字符限制：
* **V4**：`prompt` 3000字符，`style` 200字符
* **V4\_5 和 V4\_5PLUS**：`prompt` 5000字符，`style` 1000字符
* **V4\_5ALL**：`prompt` 5000字符，`style` 1000字符
* **V5**：`prompt` 5000字符，`style` 1000字符
* **V5\_5**：与 **V5** 相同的 `prompt` / `style` 限制（释放你的声音：定制模型，贴合你的独特品味）
* `title` 长度限制：80字符（所有模型）
* 非自定义模式下（`customMode: false`）:
* `prompt` 长度限制：500字符
* `instrumental`: 是否生成纯音乐
* 其他参数应留空
### 可选参数
以下字段为可选控制项：
* vocalGender（string）：偏好人声性别。允许值：`m`（男）、`f`（女）
* styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
* weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
* audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
```json 请求示例 theme={null}
{
"uploadUrlList": [
"https://example.com/audio1.mp3",
"https://example.com/audio2.mp3"
],
"customMode": true,
"prompt": "一段融合电子和摇滚元素的动感混音",
"style": "电子舞曲",
"title": "混音作品",
"model": "V4_5ALL",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.65,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
```
### 开发者注意事项
* 新用户建议：以 `customMode: false` 开始使用，更简单
* 生成的文件将保留14天
* 回调过程分三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）
* `uploadUrlList` 中的两个音频文件必须是有效且可访问的URL
* 音频文件应为支持的格式（MP3、WAV等）
## 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@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/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`）：当 `instrumental` 为 `false`
时必填。提示词将严格作为歌词使用并在生成的音轨中演唱。不同模型的字符限制：
- **V4**：最大 3000 字符
- **V4_5 和 V4_5PLUS**：最大 5000 字符
- **V4_5ALL**：最大 5000 字符
- **V5**：最大 5000 字符
- **V5_5**：最大 5000 字符（与 **V5** 相同）
示例："一段平静舒缓的钢琴曲，带有柔和的旋律"
- 在非自定义模式下（`customMode:
false`）：始终必填。提示词作为核心创意，歌词将根据它自动生成（不严格匹配输入）。最大 500 字符。
示例："一段简短放松的钢琴曲"
example: 一段平静舒缓的钢琴曲，带有柔和的旋律
style:
type: string
description: |-
生成音频的音乐风格规范。
- 仅在自定义模式下（`customMode: true`）可用且必填。定义流派、情绪或艺术方向。
- 不同模型的字符限制：
- **V4**：最大 200 字符
- **V4_5 和 V4_5PLUS**：最大 1000 字符
- **V4_5ALL**：最大 1000 字符
- **V5**：最大 1000 字符
- **V5_5**：最大 1000 字符（与 **V5** 相同）
- 常见示例：爵士、古典、电子、流行、摇滚、嘻哈等。
example: 爵士
title:
type: string
description: |-
生成音乐轨道的标题。
- 仅在自定义模式下（`customMode: true`）可用且必填。
- 最大长度：80 字符。
- 将在播放器界面和文件名中显示。
example: 宁静钢琴
customMode:
type: boolean
description: |-
确定是否启用高级参数自定义。
- 如果为 `true`：允许通过 `style` 和 `title` 字段进行详细控制。
- 如果为 `false`：简化模式，仅需要 `prompt`，其他参数将被忽略。
example: true
instrumental:
type: boolean
description: |-
确定音频是否应为纯音乐（无歌词）。
- 在自定义模式下（`customMode: true`）：
- 如果为 `true`：仅需要 `style` 和 `title`。
- 如果为 `false`：需要 `style`、`title` 和 `prompt`（提示词将作为精确歌词使用）。
- 在非自定义模式下（`customMode: false`）：不影响必填字段（仅 `prompt`）。
example: true
model:
type: string
description: |-
用于生成的AI模型版本。
- 所有请求都必填。
- 可用选项：
- **`V5`**：更卓越的音乐表现力，生成速度更快。
- **`V5_5`**：释放你的声音：定制模型，贴合你的独特品味。与 **V5** 的自定义模式下 `prompt`、`style` 字数上限一致（5000 / 1000）。
- **`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
- V5_5
example: V4
callBackUrl:
type: string
format: uri
description: >-
接收音乐生成任务完成更新的URL。所有音乐生成请求都需要。
- 系统将在生成完成时向此URL发送POST任务状态和结果
- 回调过程有三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成）
- 注意：某些情况可能会跳过 `text` 和 `first` 阶段，直接返回 `complete`
- 您的回调端点应接受包含任务结果和音频URL的JSON负载的POST请求
- 详细的回调格式和实现指南，请参见
[音乐生成回调](https://docs.kie.ai/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与"获取音乐详情"接口查询任务详情和结果。
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": "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: 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
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://api.box/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **⚠️ 注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````