当您向Suno API的 /api/v1/generate/add-vocals 接口提交人声生成任务时，可以使用 callBackUrl 参数设置回调URL。任务完成时，系统将自动向您指定的地址推送结果。
相关API接口
此回调由以下API接口触发：
添加人声接口
POST /api/v1/generate/add-vocals - 为上传的音乐文件添加人声
回调机制概述
回调机制消除了轮询API获取任务状态的需要。系统会主动向您的服务器推送任务完成结果。
回调时机
系统将在以下情况发送回调通知：
- 文本生成完成（callbackType: “text”）
- 第一个音频轨道生成完成（callbackType: “first”）
- 所有音频轨道生成完成（callbackType: “complete”）
- 人声生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP方法: POST
- 内容类型: application/json
- 超时设置: 15秒
回调请求格式
当任务进行或完成时，系统将以下格式向您的 callBackUrl 发送POST请求：
{
"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-v4-5",
"title": "钢铁侠",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
}
]
}
}
状态码说明
| 状态码 | 说明 |
|---|
| 200 | 成功 - 请求已成功处理 |
| 400 | 验证错误 - 歌词包含受版权保护的内容 |
| 408 | 超出限制 - 超时 |
| 413 | 冲突 - 上传的音频与现有艺术作品匹配 |
| 500 | 服务器错误 - 处理请求时发生意外错误 |
| 501 | 音频生成失败 |
| 531 | 服务器错误 - 抱歉，由于问题生成失败。您的积分已退还。请重试 |
回调接收示例
以下是常用编程语言的回调接收示例代码：
const express = require('express');
const app = express();
app.use(express.json());
app.post('/vocals-callback', (req, res) => {
const { code, msg, data } = req.body;
console.log('收到人声回调:', {
taskId: data.task_id,
status: code,
message: msg,
callbackType: data.callbackType
});
if (code === 200) {
// 任务成功完成
if (data.callbackType === 'complete') {
console.log('人声生成完成:', data.data);
// 处理生成的人声数据
data.data.forEach(audio => {
console.log(`音频ID: ${audio.id}`);
console.log(`音频URL: ${audio.audio_url}`);
console.log(`标题: ${audio.title}`);
console.log(`时长: ${audio.duration} 秒`);
});
} else if (data.callbackType === 'first') {
console.log('第一首生成完成');
} else if (data.callbackType === 'text') {
console.log('文本生成完成');
}
} else {
// 任务失败
console.log('任务失败:', msg);
}
// 返回200状态码确认接收回调
res.status(200).json({ status: 'received' });
});
app.listen(3000, () => {
console.log('人声回调服务器运行在端口3000');
});
最佳实践
回调URL配置建议
- 使用HTTPS: 确保您的回调URL使用HTTPS协议，保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个task_id可能会收到多次回调，确保处理逻辑具有幂等性
- 快速响应: 回调处理应尽快返回200状态码，避免超时
- 异步处理: 复杂的业务逻辑应异步处理，避免阻塞回调响应
- 阶段跟踪: 根据callbackType区分不同生成阶段，合理安排业务逻辑
重要提醒
- 回调URL必须是公网可访问的地址
- 服务器必须在15秒内响应，否则将被视为超时
- 如果连续3次重试失败，系统将停止发送回调
- 请确保回调处理逻辑的稳定性，避免因异常导致回调失败
- 注意处理不同callbackType的回调，特别是complete类型的最终结果
替代方案
如果您无法使用回调机制，也可以使用轮询方式：
轮询查询结果
使用获取音乐详情端点定期查询任务状态。建议每30秒查询一次。
