{
"instrumental": false,
"lyrics": "[Verse] 夜晚城市 灯火辉煌",
"style": "Cinematic",
"title": "暗黑翻唱",
"uploadUrl": "https://storage.example.com/upload",
"variety": 1,
"model": "V6",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}Generate Music
上传并翻唱音乐
此 API 通过在保留其核心旋律的同时将音轨转换为新样式来覆盖音轨。它结合了 Suno 的上传功能，使用户能够上传音频文件进行处理。预期的结果是刷新了具有新风格的音轨，同时保持了原始旋律的完整性。
POST
/
api
/
v1
/
generate
/
upload-cover
{
"instrumental": false,
"lyrics": "[Verse] 夜晚城市 灯火辉煌",
"style": "Cinematic",
"title": "暗黑翻唱",
"uploadUrl": "https://storage.example.com/upload",
"variety": 1,
"model": "V6",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}模型版本
- 当前模型：
V6（默认）、V6_WILD、V6_MINI - 已废弃模型：
V5_5、V5、V4_5PLUS、V4_5ALL、V4_5、V4 - 废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。
参数使用指南
- 本接口固定为自定义模式，简单模式不可用。源音频输入方式二选一：提供
uploadUrl，或同时提供taskId和audioId以使用已有生成音频。两种方式不可同时使用。 lyrics（或prompt）、title、style均为选填。- 必填：
uploadUrl，或同时提供taskId和audioId，以及model和callBackUrl - model（string，必填）：
V6、V6_WILD、V6_MINI。已废弃：V4_5ALL、V4、V4_5、V4_5PLUS、V5、V5_5。 prompt按歌词语义使用。可选。若同时传入lyrics，优先使用lyrics，prompt不再作为歌词。- 字符限制（基于模型）：
- V4 模型（已废弃）：prompt 最多 3000 字符，style 最多 200 字符
- V4_5、V4_5PLUS、V5、V5_5 和 V4_5ALL 模型（已废弃）：prompt 最多 5000 字符，style 最多 1000 字符
- V6、V6_WILD 和 V6_MINI 模型：lyrics/prompt 最多 5000 字符，style 最多 1000 字符，title 最多 80 字符
uploadUrl用于指定源音频文件；使用上传方式时请确保音频长度不超过 8 分钟。taskId为已有音乐生成任务的任务 ID，audioId为已有音乐 ID。使用已有生成音频时必须同时提供这两个参数。
可选参数
以下字段为可选控制项：
- lyrics（string）：歌词内容。可选。V6 系列最多 5000 字符。优先于
prompt作为歌词。 - prompt（string）：歌词内容。可选。未传入
lyrics时作为歌词使用。V6 系列最多 5000 字符。 - style（string）：音乐风格。可选。V6 系列最多 1000 字符。
- title（string）：曲目标题。可选。最多 80 字符。
- instrumental（boolean）：是否生成纯音乐。默认
false。 - vocalGender（string）：偏好人声性别。允许值：
m（男）、f（女） - styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
- weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
- audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
- variety（number）：生成结果的多样性。范围 0–4 的整数，默认 1。
0关闭，1普通（默认），2高，3额外，4最大。 - personaId（string）：Persona ID 或 Suno Voice 生成的
voiceId。如果使用 Voice 生成的 ID，personaModel必须设置为voice_persona。 - personaModel（string）：Persona 类型。生成 Persona 接口返回的 ID 使用
style_persona，Suno Voice 生成的 ID 使用voice_persona。默认style_persona。
{
"instrumental": false,
"lyrics": "[Verse] 夜晚城市 灯火辉煌",
"style": "Cinematic",
"title": "暗黑翻唱",
"uploadUrl": "https://storage.example.com/upload",
"variety": 1,
"model": "V6",
"callBackUrl": "https://example.com/callback",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65
}
{
"instrumental": false,
"taskId": "5c79****be8e",
"audioId": "e231****-****-****-****-****8cadc7dc",
"model": "V6",
"callBackUrl": "https://example.com/callback"
}
开发者注意事项
- 新用户推荐设置：提供
uploadUrl、model和callBackUrl。lyrics、title、style均为选填。 - 生成的文件将保留15天后删除
- 请注意 lyrics/prompt、style 和 title 的字符长度限制，确保成功处理
- 回调过程有三个阶段：text（文本生成完成）、first（第一首完成）、complete（全部完成）
- 您可以使用音乐生成详情查询接口主动检查任务状态，而不必等待回调
- uploadUrl 参数用于指定源音频文件；使用上传方式时请提供有效的 URL。
授权
🔑 API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
获取 API Key
- 访问 API Key 管理页面 获取您的 API Key
使用方式
在请求头中添加：
Authorization: Bearer YOUR_API_KEY
⚠️ 注意：
- 请妥善保管您的 API Key，不要泄露给他人
- 如果怀疑 API Key 泄露，请立即在管理页面重置
请求体
application/json
- 使用上传音频进行翻唱
- 使用已有音频进行翻唱
用于翻唱的源音频文件 URL。使用上传音频时必填。不可与 taskId 和 audioId 同时使用。
上传音频时长限制： 最大上传时长为 8 分钟
示例:
"https://api.example.com/upload"
AI 模型版本。默认值：V6。
V6：当前标准模型，推荐默认使用。V6_WILD：当前实验性、创造性更强的模型。V6_MINI：当前轻量模型。- 已废弃：
V5_5、V5、V4_5PLUS、V4_5ALL、V4_5、V4。这些值仅为向后兼容保留，新接入请使用 V6 系列模型。
可用选项:
V6, V6_WILD, V6_MINI, V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4 示例:
"V6"
歌词内容。可选。未传入 lyrics 时作为歌词使用；若同时传入 lyrics，优先使用 lyrics，本字段不再作为歌词。
- V4（已废弃）：最多 3000 字符
- V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）：最多 5000 字符
- V6、V6_WILD、V6_MINI：最多 5000 字符
示例:
"[Verse] 夜晚城市 灯火辉煌"
歌词内容。可选。V6、V6_MINI、V6_WILD 最多 5000 字符。优先于 prompt 作为歌词；未传入时使用 prompt 作为歌词。
示例:
"[Verse] 夜晚城市 灯火辉煌"
音乐风格，例如爵士、古典、电子等。可选。V6、V6_WILD、V6_MINI 最多 1000 字符。
- V4（已废弃）：最多 200 字符
- V4_5、V4_5PLUS、V4_5ALL、V5、V5_5（已废弃）：最多 1000 字符
示例:
"古典"
音乐标题。可选。最多 80 字符。
Maximum string length:
80示例:
"宁静钢琴冥想"
决定音频是否为纯音乐（无歌词）。可选。默认 false。
示例:
true
应用到生成音乐的 Persona ID，可选。你可以传入以下两类 ID：
- 通过 生成 Persona 接口生成的 Persona ID。此时可使用
personaModel: style_persona，或省略personaModel使用默认值。 - 通过 Suno Voice 流程生成的
voiceId。当使用 Voice 生成的 ID 时，必须设置personaModel: voice_persona。
示例:
"persona_123"
使用 personaId 时应用的 Persona 模型类型，可选。
style_persona（默认）：用于生成 Persona 接口返回的 Persona ID。voice_persona：当personaId使用 Suno Voice 生成的voiceId时必须选择该值。该选项仅在 V5（已废弃）、V5_5（已废弃）、V6、V6_WILD 和 V6_MINI 模型下可用。
可用选项:
style_persona, voice_persona 示例:
"style_persona"
需要在生成的音频中排除的音乐风格或特征。
- 可选。用于避免特定风格。
示例："重金属, 强节奏鼓点"
示例:
"重金属, 强节奏鼓点"
偏好人声性别。可选。允许值：m（男）、f（女）。
可用选项:
m, f 示例:
"m"
风格贴合权重。可选。范围 0–1，建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.65
创造性/新颖度约束。可选。范围 0–1，建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.65
音频一致性与其他控制项的相对权重。可选。范围 0–1，建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.65
控制生成结果的多样性和风格差异程度。可选。范围 0–4 的整数，默认值为 1。
0：off（exact style），完全关闭，严格用同一风格1：normal（balanced variety），默认值，在稳定性和多样性之间保持平衡2：high（distinct styles），生成风格差异明显的结果3：extra（bold exploration），提供更高程度的变化，鼓励大胆探索不同风格4：max（unreasonably varied），最大程度增加多样性，生成结果可能具有非常明显的风格差异
必填范围:
0 <= x <= 4必须是以下数值的倍数 1示例:
1
时长（秒）。可选。范围 10–360。仅当 model 为 V5_5（已废弃）、V6、V6_WILD 或 V6_MINI 时有效。
必填范围:
10 <= x <= 360示例:
20
回调
响应
请求成功
状态码说明
- ✅ 200 - 请求成功
- ⚠️ 400 - 参数错误
- ⚠️ 401 - 没有访问权限
- ⚠️ 404 - 请求方式或者路径错误
- ⚠️ 405 - 调用超过限制
- ⚠️ 413 - 主题或者prompt过长
- ⚠️ 429 - 积分不足
- ⚠️ 430 - 您的调用频率过高。请稍后再试。
- ⚠️ 455 - 网站维护
- ❌ 500 - 服务器异常
可用选项:
200, 400, 401, 404, 405, 413, 429, 430, 455, 500 示例:
200
当 code != 200 时，展示错误信息
示例:
"success"
Show child attributes
Show child attributes