{
"taskId": "2fac****9f72",
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}Generate Music
替换音乐分区
替换现有音乐的指定时间段。
POST
/
api
/
v1
/
generate
/
replace-section
{
"taskId": "2fac****9f72",
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}模型版本
- 当前模型：
V6（默认）、V6_WILD、V6_MINI - 已废弃模型：
V5_5、V5、V4_5PLUS、V4_5ALL、V4_5、V4 - 废弃值仅为向后兼容保留，新接入请使用 V6 系列模型。
参数使用指南
本接口固定为自定义参数，简单模式不可用。 此端点支持两种指定源音频的模式： 模式一：使用已有音频进行分区替换- 需要提供
taskId和audioId - 不能提供
uploadUrl和model
- 需要提供
uploadUrl和model - 不能提供
taskId和audioId
公共必需参数
- prompt（string，必填）：替换后的歌词
- tags（string，必填）：音乐的风格标签，如爵士、电子等
- title（string，必填）：音乐的标题
- infillStartS（number，必填）：开始替换的时间点（秒），保留2位小数。必须小于 infillEndS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
- infillEndS（number，必填）：结束替换的时间点（秒），保留2位小数。必须大于 infillStartS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
- fullLyrics（string，必填）：修改后的完整歌词，包含修改和未修改歌词的合并
歌词相关字段的分工
本接口有三个承载歌词的字段，作用范围各不相同：- fullLyrics（必填）：替换之后整首歌的完整歌词，包含修改与未修改部分的合并。上游据此重算并对齐替换片段的提示。
- lyrics（选填）：仅替换片段所用的歌词。
- prompt（必填）：替换后的歌词，为兼容旧接入保留。
可选参数
以下字段为可选控制项：
- lyrics（string）：替换片段所用歌词。V6、V6_WILD、V6_MINI 最多 5000 字符。
- negativeTags（string）：排除的音乐风格，用于避免特定风格元素出现在替换片段中
- vocalGender（string）：偏好人声性别。允许值：
m（男）、f（女） - styleWeight（number）：风格贴合权重，范围 0–1（建议保留两位小数）
- weirdnessConstraint（number）：创造性/新颖度约束，范围 0–1（建议保留两位小数）
- audioWeight（number）：音频一致性相对权重，范围 0–1（建议保留两位小数）
- variety（integer）：生成结果的多样性。范围 0–4 的整数，默认 1。
0关，1普通（默认），2高，3额外，4最大。 - personaId（string）：应用到生成音乐的 Persona ID 或 Suno Voice 生成的
voiceId。如果使用 Voice 生成的 ID，personaModel必须设置为voice_persona。 - personaModel（string）：Persona 类型，默认
style_persona。生成 Persona 接口返回的 ID 使用style_persona，Suno Voice 生成的 ID 使用voice_persona。 - callBackUrl（string）：生成任务完成后的回调URL。详细回调格式请参见 替换音乐分区回调。
时间范围说明
infillStartS必须小于infillEndS- 时间值精确到小数点后 2 位，例如：
10.50秒 - 替换时间范围至少为 10 秒
- 替换时长建议不超过原音乐总时长的 50%
{
"taskId": "2fac****9f72",
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"lyrics": "[副歌]\n此部分的修改歌词",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"variety": 1,
"callBackUrl": "https://example.com/callback"
}
开发者注意事项
- 替换片段会根据提供的
prompt和tags重新生成 - 生成的替换片段会自动与原音乐前后部分融合
- 生成的文件将保留 14 天
- 查询任务状态使用与生成音乐相同的接口：获取音乐详情
授权
🔑 API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
获取 API Key
- 访问 API Key 管理页面 获取您的 API Key
使用方式
在请求头中添加：
Authorization: Bearer YOUR_API_KEY
⚠️ 注意：
- 请妥善保管您的 API Key，不要泄露给他人
- 如果怀疑 API Key 泄露，请立即在管理页面重置
请求体
application/json
- 使用已有音频进行分区替换
- 使用用户上传音频进行分区替换
原始任务ID（父任务），用于标识要进行分区替换的源音乐。
示例:
"2fac****9f72"
要替换的音频曲目的唯一标识符。此ID在音乐生成完成后的回调数据中返回。
示例:
"e231****-****-****-****-****8cadc7dc"
替换后的歌词
示例:
"A calm and relaxing piano track."
音乐的风格标签，如爵士、电子等
示例:
"Jazz"
音乐的标题
示例:
"Relaxing Piano"
开始替换的时间点（秒），保留2位小数。必须小于 infillEndS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
必填范围:
x >= 0示例:
10.5
结束替换的时间点（秒），保留2位小数。必须大于 infillStartS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
必填范围:
x >= 0示例:
20.75
修改后的完整歌词，包含修改和未修改歌词的合并。此参数包含在分区替换后整首歌曲将使用的完整歌词文本。
示例:
"[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词"
排除的音乐风格，用于避免特定风格元素出现在替换片段中
示例:
"Rock"
替换片段所用歌词。选填。fullLyrics 为整首歌的完整歌词，lyrics 只对应被替换的那一段。
- V6、V6_WILD 和 V6_MINI：最多5000字符
示例:
"[Chorus] 灯火更亮，我们继续向前"
偏好人声性别。可选。允许值：'m'（男）、'f'（女）
可用选项:
m, f 示例:
"m"
风格权重。可选。范围：0-1。建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.61
创意/新颖性约束。可选。范围：0-1。建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.72
音频一致性与其他控制的相对权重。可选。范围：0-1。建议保留两位小数。
必填范围:
0 <= x <= 1必须是以下数值的倍数 0.01示例:
0.65
生成结果的多样性。可选。范围 0–4 的整数，默认值为 1。
0：关，完全关闭，严格用同一风格1：普通，默认值，在稳定性和多样性之间保持平衡2：高，生成风格差异明显的结果3：额外，更高程度的变化，鼓励大胆探索4：最大，最大程度增加多样性
必填范围:
0 <= x <= 4必须是以下数值的倍数 1示例:
1
应用到生成音乐的 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"
回调
POST{request.body#/callBackUrl}audioGenerated
请求体
application/json
响应
请求成功
响应状态码
- 200: 成功 - 请求已成功处理
- 401: 未授权 - 身份验证凭据缺失或无效
- 402: 积分不足 - 账户没有足够的积分执行此操作
- 404: 未找到 - 请求的资源或端点不存在
- 409: 冲突 - WAV记录已存在
- 422: 验证错误 - 请求参数未通过验证检查
- 429: 超出限制 - 已超过对此资源的请求限制
- 451: 未授权 - 获取图像失败。请验证您或您的服务提供商设置的任何访问限制。
- 455: 服务不可用 - 系统当前正在进行维护
- 500: 服务器错误 - 处理请求时发生意外错误
可用选项:
200, 401, 402, 404, 409, 422, 429, 451, 455, 500 当 code != 200 时的错误信息
示例:
"success"
Show child attributes
Show child attributes