当您向Suno API的 /api/v1/generate/add-vocals 接口提交人声生成任务时，可以使用 callBackUrl 参数设置回调URL。任务完成时，系统将自动向您指定的地址推送结果。
相关API接口
此回调由以下API接口触发：
添加人声接口
POST /api/v1/generate/add-vocals - 为上传的音乐文件添加人声
回调机制概述
Webhook 安全性：为确保回调请求的真实性和完整性，我们强烈建议您实现 webhook 签名验证。请参阅我们的 Webhook 校验指南 了解详细实现步骤。 回调机制消除了轮询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');
});
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/vocals-callback', methods=['POST'])
def handle_callback():
data = request.json
code = data.get('code')
msg = data.get('msg')
callback_data = data.get('data', {})
task_id = callback_data.get('task_id')
callback_type = callback_data.get('callbackType')
print(f"收到人声回调: {task_id}, 状态: {code}, 类型: {callback_type}")
if code == 200:
# 任务成功完成
if callback_type == 'complete':
audio_list = callback_data.get('data', [])
print(f"人声生成完成，生成了 {len(audio_list)} 个音轨")
for audio in audio_list:
print(f"音频ID: {audio['id']}")
print(f"音频URL: {audio['audio_url']}")
print(f"标题: {audio['title']}")
print(f"时长: {audio['duration']} 秒")
elif callback_type == 'first':
print("第一首生成完成")
elif callback_type == 'text':
print("文本生成完成")
else:
# 任务失败
print(f"任务失败: {msg}")
# 返回200状态码确认接收回调
return jsonify({'status': 'received'}), 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000)
<?php
header('Content-Type: application/json');
// 获取POST数据
$input = file_get_contents('php://input');
$data = json_decode($input, true);
$code = $data['code'] ?? null;
$msg = $data['msg'] ?? '';
$callbackData = $data['data'] ?? [];
$taskId = $callbackData['task_id'] ?? '';
$callbackType = $callbackData['callbackType'] ?? '';
error_log("收到人声回调: $taskId, 状态: $code, 类型: $callbackType");
if ($code === 200) {
// 任务成功完成
if ($callbackType === 'complete') {
$audioList = $callbackData['data'] ?? [];
error_log("人声生成完成，生成了 " . count($audioList) . " 个音轨");
foreach ($audioList as $audio) {
error_log("音频ID: " . $audio['id']);
error_log("音频URL: " . $audio['audio_url']);
error_log("标题: " . $audio['title']);
error_log("时长: " . $audio['duration'] . " 秒");
}
} elseif ($callbackType === 'first') {
error_log("第一首生成完成");
} elseif ($callbackType === 'text') {
error_log("文本生成完成");
}
} else {
// 任务失败
error_log("任务失败: $msg");
}
// 返回200状态码确认接收回调
http_response_code(200);
echo json_encode(['status' => 'received']);
?>
最佳实践
回调URL配置建议
- 使用HTTPS: 确保您的回调URL使用HTTPS协议，保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个task_id可能会收到多次回调，确保处理逻辑具有幂等性
- 快速响应: 回调处理应尽快返回200状态码，避免超时
- 异步处理: 复杂的业务逻辑应异步处理，避免阻塞回调响应
- 阶段跟踪: 根据callbackType区分不同生成阶段，合理安排业务逻辑
重要提醒
- 回调URL必须是公网可访问的地址
- 服务器必须在15秒内响应，否则将被视为超时
- 如果连续3次重试失败，系统将停止发送回调
- 请确保回调处理逻辑的稳定性，避免因异常导致回调失败
- 注意处理不同callbackType的回调，特别是complete类型的最终结果
替代方案
如果您无法使用回调机制，也可以使用轮询方式：
轮询查询结果
使用获取音乐详情端点定期查询任务状态。建议每30秒查询一次。
