{
"taskId": "2fac****9f72",
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"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.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"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，必填）：替换片段的歌词。若同时传入
lyrics，替换片段优先使用lyrics。 - tags（string，必填）：音乐的风格标签，如爵士、电子等
- title（string，必填）：音乐的标题
- infillStartS（number，必填）：开始替换的时间点（秒），保留2位小数。必须小于 infillEndS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
- infillEndS（number，必填）：结束替换的时间点（秒），保留2位小数。必须大于 infillStartS，且 infillEndS 与 infillStartS 的时间差必须至少为10 秒。
- fullLyrics（string，必填）：修改后的完整歌词，包含修改和未修改歌词的合并。与仅作用于替换片段的
lyrics/prompt不同。
可选参数
以下字段为可选控制项：
- lyrics（string）：替换片段的歌词。可选。V6 系列最多 5000 字符。优先于
prompt作为替换片段歌词。与表示整首歌词的fullLyrics分工不同。 - negativeTags（string）：排除的音乐风格，用于避免特定风格元素出现在替换片段中
- 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。 - callBackUrl（string）：生成任务完成后的回调URL。详细回调格式请参见 替换音乐分区回调。
时间范围说明
infillStartS必须小于infillEndS- 时间值精确到小数点后 2 位，例如：
10.50秒 - 替换时间范围至少为 10 秒
- 替换时长建议不超过原音乐总时长的 50%
{
"taskId": "2fac****9f72",
"audioId": "e231****-****-****-****-****8cadc7dc",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
{
"uploadUrl": "https://example.com/audio.mp3",
"model": "V6",
"prompt": "A calm and relaxing piano track.",
"tags": "Jazz",
"title": "Relaxing Piano",
"negativeTags": "Rock",
"infillStartS": 10.5,
"infillEndS": 20.75,
"fullLyrics": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
"callBackUrl": "https://example.com/callback"
}
开发者注意事项
- 替换片段会根据提供的
lyrics/prompt和tags重新生成。lyrics（或prompt）只作用于替换片段，fullLyrics是整首歌词。 - 生成的替换片段会自动与原音乐前后部分融合
- 生成的文件将保留 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"
替换片段的歌词。必填。若同时传入 lyrics，替换片段优先使用 lyrics。
示例:
"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
修改后的完整歌词，包含修改和未修改歌词的合并。与仅作用于替换片段的 lyrics（以及 prompt）不同。此参数包含分区替换后整首歌曲将使用的完整歌词文本。
示例:
"[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词"
歌词内容。可选。V6、V6_MINI、V6_WILD 最多 5000 字符。 替换片段的歌词。与表示整首歌词的 fullLyrics 分工不同。
示例:
"[Verse] 夜晚城市 灯火辉煌"
排除的音乐风格，用于避免特定风格元素出现在替换片段中
示例:
"Rock"
偏好人声性别。可选。允许值：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
应用到生成音乐的 Persona ID 或 Voice ID。可选。若使用 Voice 生成的 ID，需将 personaModel 设为 voice_persona。
示例:
"persona_123"
Persona 模型类型。可选。style_persona（默认）用于生成 Persona 接口返回的 ID；voice_persona 用于 Suno Voice 生成的 voiceId。默认 style_persona。
可用选项:
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