Suno Voice 验证短句回调
当 Suno Voice 验证短句生成完成时，系统会调用此回调。
当您向 Suno Voice API 提交验证短句生成任务时，可以使用 callBackUrl 参数设置一个回调地址。任务完成后，系统会自动将验证短句结果推送到您指定的地址。
回调机制概述
Webhook 安全说明
为确保回调请求的真实性和完整性，我们强烈建议您实现 Webhook 签名验证。详细实现步骤请参考我们的 Webhook 验证指南。
回调时机
系统会在以下情况下发送回调通知：
- 验证短句生成成功
- 验证短句生成失败
- 验证短句处理过程中出现错误
回调方式
- HTTP 方法：POST
- 内容类型：application/json
- 超时设置：15 秒
回调请求格式
当验证短句任务完成时，系统会以如下格式向您的 callBackUrl 发送 POST 请求：
Success Callback
json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "xxx_task_id_xxx",
"validateInfo": "Harmonies fill the air with joyful melodies tonight",
"status": "wait_validating"
}
}Failure Callback
json
{
"code": 500,
"msg": "Internal Error, Please try again later.",
"data": {
"taskId": "xxx_task_id_xxx",
"status": "processing_validate_fail",
"errorCode": 500,
"errorMessage": "Failed to generate validation phrase"
}
}状态码说明
code（整数，必填）
回调状态码，表示任务处理结果：
| 状态码 | 说明 |
|---|---|
| 200 | 成功 - 验证短句已成功生成 |
| 500 | 失败 - 验证短句生成失败或内部处理错误 |
msg（字符串，必填）
状态消息，提供详细的状态描述。
data.taskId（字符串，必填）
任务 ID，与您提交验证短句任务时返回的 taskId 一致。
data.validateInfo（字符串）
验证短句文本。验证短句生成成功时返回。
data.status（字符串）
当前任务状态。
| 状态 | 说明 |
|---|---|
| wait_processing | 等待验证短句处理 |
| processing_validate | 正在生成验证短句 |
| processing_validate_fail | 验证短句生成失败 |
| wait_validating | 验证短句已就绪，等待用户验证 |
| success | 任务成功完成 |
| fail | 任务失败 |
data.errorCode（整数）
错误码。任务成功时通常为 null。
data.errorMessage（字符串）
详细错误信息。任务成功时通常为空。
回调接收示例
以下是主流编程语言接收回调的示例代码：
Node.js
javascript
const express = require('express');
const app = express();
app.use(express.json());
app.post('/suno-voice-validate-callback', (req, res) => {
const { code, msg, data } = req.body;
console.log('收到 Suno Voice 验证短句回调：', {
taskId: data.taskId,
status: data.status,
message: msg
});
if (code === 200 && data.status === 'wait_validating') {
console.log('验证短句已就绪');
console.log(`验证短句：${data.validateInfo}`);
} else {
console.log('验证短句生成失败：', data.errorMessage || msg);
}
res.status(200).json({ status: 'received' });
});
app.listen(3000, () => {
console.log('回调服务器运行在端口 3000');
});Python
python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/suno-voice-validate-callback', methods=['POST'])
def handle_callback():
payload = request.json
code = payload.get('code')
msg = payload.get('msg')
data = payload.get('data', {})
task_id = data.get('taskId')
status = data.get('status')
validate_info = data.get('validateInfo')
error_message = data.get('errorMessage')
print(f"收到 Suno Voice 验证短句回调：{task_id}, 状态：{status}")
if code == 200 and status == 'wait_validating':
print("验证短句已就绪")
print(f"验证短句：{validate_info}")
else:
print(f"验证短句生成失败：{error_message or msg}")
return jsonify({'status': 'received'}), 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000)PHP
php
<?php
header('Content-Type: application/json');
$input = file_get_contents('php://input');
$payload = json_decode($input, true);
$code = $payload['code'] ?? null;
$msg = $payload['msg'] ?? '';
$data = $payload['data'] ?? [];
$taskId = $data['taskId'] ?? '';
$status = $data['status'] ?? '';
$validateInfo = $data['validateInfo'] ?? '';
$errorMessage = $data['errorMessage'] ?? '';
error_log("收到 Suno Voice 验证短句回调：$taskId, 状态：$status");
if ($code === 200 && $status === 'wait_validating') {
error_log("验证短句已就绪：$validateInfo");
} else {
error_log("验证短句生成失败：" . ($errorMessage ?: $msg));
}
http_response_code(200);
echo json_encode(['status' => 'received']);
?>最佳实践
回调地址配置建议
- 使用 HTTPS：确保回调地址使用 HTTPS 协议，保障数据传输安全
- 验证来源：在回调处理中验证请求来源的合法性
- 幂等处理：同一个 taskId 可能会收到多次回调，请确保处理逻辑具有幂等性
- 快速响应：回调处理应尽快返回 200 状态码，避免超时
- 异步处理：复杂业务逻辑应异步处理，避免阻塞回调响应
- 持久化 validateInfo：将验证短句与 taskId 一起保存，便于用户读取正确的短句
重要提醒
- 回调地址必须是公网可访问的地址
- 服务器必须在 15 秒内响应，否则将被视为超时
- 若连续 3 次重试失败，系统将停止发送回调
- 请确保回调处理逻辑的稳定性，避免因异常导致回调失败
- 验证短句应在用户提交验证音频之前展示给用户
常见问题排查
如果您没有收到回调通知，请检查以下内容：
网络连接问题
- 确认回调地址可从公网访问
- 检查防火墙设置，确保入站请求未被拦截
- 验证域名解析是否正确
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志中是否有错误信息
- 确认接口路径和 HTTP 方法是否正确
内容格式问题
- 确认收到的 POST 请求体为 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析是否正确