{
  "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
}

{
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

POST

api

generate

mashup

{
  "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
}

{
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

使用指南

此接口从最多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（建议保留两位小数）

{
  "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等）

授权

Authorization

string

header

必填

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

访问 API Key 管理页面获取您的 API Key

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

⚠️ 注意：

请妥善保管您的 API Key，不要泄露给他人

如果怀疑 API Key 泄露，请立即在管理页面重置

请求体

application/json

uploadUrlList

string<uri>[]

必填

用于混音的音频文件URL数组。必须包含恰好2个URL。每个URL必须是公网可访问的。

Required array length: 2 elements

示例:

[
  "https://example.com/audio1.mp3",
  "https://example.com/audio2.mp3"
]

customMode

boolean

必填

确定是否启用高级参数自定义。

如果为 true：允许通过 style 和 title 字段进行详细控制。
如果为 false：简化模式，仅需要 prompt，其他参数将被忽略。

示例:

true

model

enum<string>

必填

用于生成的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分钟。

可用选项:

V4,

V4_5,

V4_5PLUS,

V4_5ALL,

V5,

V5_5

示例:

"V4"

callBackUrl

string<uri>

必填

接收音乐生成任务完成更新的URL。所有音乐生成请求都需要。

系统将在生成完成时向此URL发送POST任务状态和结果
回调过程有三个阶段：text（文本生成）、first（第一首完成）、complete（全部完成）
注意：某些情况可能会跳过 text 和 first 阶段，直接返回 complete
您的回调端点应接受包含任务结果和音频URL的JSON负载的POST请求
详细的回调格式和实现指南，请参见音乐生成回调
或者，使用获取音乐详情接口来轮询任务状态
为确保回调安全，请参见 Webhook 验证指南了解签名验证实现

示例:

"https://example.com/callback"

prompt

string

所需音频内容的描述。

在自定义模式下（customMode: true）：当 instrumental 为 false 时必填。提示词将严格作为歌词使用并在生成的音轨中演唱。不同模型的字符限制：
- V4：最大 3000 字符
- V4_5 和 V4_5PLUS：最大 5000 字符
- V4_5ALL：最大 5000 字符
- V5：最大 5000 字符
- V5_5：最大 5000 字符（与 V5 相同）
  示例："一段平静舒缓的钢琴曲，带有柔和的旋律"
在非自定义模式下（customMode: false）：始终必填。提示词作为核心创意，歌词将根据它自动生成（不严格匹配输入）。最大 500 字符。
示例："一段简短放松的钢琴曲"

示例:

"一段平静舒缓的钢琴曲，带有柔和的旋律"

style

string

生成音频的音乐风格规范。

仅在自定义模式下（customMode: true）可用且必填。定义流派、情绪或艺术方向。
不同模型的字符限制：
- V4：最大 200 字符
- V4_5 和 V4_5PLUS：最大 1000 字符
- V4_5ALL：最大 1000 字符
- V5：最大 1000 字符
- V5_5：最大 1000 字符（与 V5 相同）
常见示例：爵士、古典、电子、流行、摇滚、嘻哈等。

示例:

"爵士"

title

string

生成音乐轨道的标题。

仅在自定义模式下（customMode: true）可用且必填。
最大长度：80 字符。
将在播放器界面和文件名中显示。

示例:

"宁静钢琴"

instrumental

boolean

确定音频是否应为纯音乐（无歌词）。

在自定义模式下（customMode: true）：
- 如果为 true：仅需要 style 和 title。
- 如果为 false：需要 style、title 和 prompt（提示词将作为精确歌词使用）。
在非自定义模式下（customMode: false）：不影响必填字段（仅 prompt）。

示例:

true

vocalGender

enum<string>

演唱声音的人声性别偏好。

仅在自定义模式下（customMode: true）可用。可选。使用 'm' 表示男性，'f' 表示女性。根据实践，此参数只能增加概率，但不能保证遵循男/女声指令。

可用选项:

m,

f

示例:

"m"

styleWeight

number

遵循指定风格的强度。

仅在自定义模式下（customMode: true）可用。可选。范围 0–1，最多2位小数。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.61

weirdnessConstraint

number

控制实验性/创意偏差。

仅在自定义模式下（customMode: true）可用。可选。范围 0–1，最多2位小数。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.72

audioWeight

number

音频特征与其他因素的平衡权重。

仅在自定义模式下（customMode: true）可用。可选。范围 0–1，最多2位小数。

必填范围: 0 <= x <= 1必须是以下数值的倍数 0.01

示例:

0.65

回调

POST

{request.body#/callBackUrl}audioGenerated

请求体

application/json

code

integer

状态码

示例:

200

msg

string

返回消息

示例:

"All generated successfully"

data

object

Show child attributes

响应

200 - application/json

回调接收成功

code

enum<integer>

响应状态码

200: 成功 - 请求已成功处理
400: 验证错误 - 歌词包含受版权保护的内容。
408: 超出限制 - 超时。
413: 冲突 - 上传的音频与现有艺术作品匹配。
500: 服务器错误 - 处理请求时发生意外错误
501: 音频生成失败。
531: 服务器错误 - 抱歉，由于问题导致生成失败。您的积分已退还。请重试。

可用选项:

200,

400,

408,

413,

500,

501,

531

msg

string

当 code != 200 时的错误信息

示例:

"success"

响应

请求成功

code

enum<integer>

响应状态码

200: 成功 - 请求已成功处理
401: 未授权 - 身份验证凭据缺失或无效
402: 积分不足 - 账户没有足够的积分执行此操作
404: 未找到 - 请求的资源或端点不存在
409: 冲突 - WAV 记录已存在
422: 验证错误 - 请求参数未通过验证检查
429: 超出限制 - 已超过对此资源的请求限制
451: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。
455: 服务不可用 - 系统当前正在进行维护
500: 服务器错误 - 处理请求时发生意外错误

可用选项:

200,

401,

402,

404,

409,

422,

429,

451,

455,

500

msg

string

当 code != 200 时的错误信息

示例:

"success"

data

object

Show child attributes

生成 Persona Suno Voice 生成验证短句

​使用指南

​参数详情

​可选参数

​开发者注意事项

授权

🔑 API 认证说明

获取 API Key

使用方式

请求体

回调

请求体

响应

响应

使用指南

参数详情

可选参数

开发者注意事项