Suno Voice 验证短句回调

当 Suno Voice 验证短句生成完成时，系统会调用此回调。

当您向 Suno Voice API 提交验证短句生成任务时，可以在 /api/v1/voice/validate 接口中使用 callBackUrl 参数设置一个回调地址。任务完成后，系统会自动将验证短句结果推送到您指定的地址。

回调机制概述

回调机制无需轮询验证短句接口来获取任务状态。系统会主动将验证短句结果推送到您的服务器。

Webhook 安全说明

为确保回调请求的真实性和完整性，我们强烈建议您实现 Webhook 签名验证。详细实现步骤请参考我们的 Webhook 验证指南。

回调时机

系统会在以下情况下发送回调通知：

验证短句生成成功

验证短句生成失败

验证短句处理过程中出现错误

回调方式

HTTP 方法：POST

内容类型：application/json

超时设置：15 秒

回调请求格式

当验证短句任务完成时，系统会以如下格式向您的 callBackUrl 发送 POST 请求：

Success Callback

Failure Callback

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx",
    "validateInfo": "Harmonies fill the air with joyful melodies tonight",
    "status": "wait_validating"
  }
}

状态码说明

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

Python

PHP

最佳实践

回调地址配置建议

使用 HTTPS：确保回调地址使用 HTTPS 协议，保障数据传输安全

验证来源：在回调处理中验证请求来源的合法性

幂等处理：同一个 taskId 可能会收到多次回调，请确保处理逻辑具有幂等性

快速响应：回调处理应尽快返回 200 状态码，避免超时

异步处理：复杂业务逻辑应异步处理，避免阻塞回调响应

持久化 validateInfo：将验证短句与 taskId 一起保存，便于用户读取正确的短句

重要提醒

回调地址必须是公网可访问的地址

服务器必须在 15 秒内响应，否则将被视为超时

若连续 3 次重试失败，系统将停止发送回调

请确保回调处理逻辑的稳定性，避免因异常导致回调失败

验证短句应在用户提交验证音频之前展示给用户

常见问题排查

如果您没有收到回调通知，请检查以下内容：

网络连接问题

确认回调地址可从公网访问

检查防火墙设置，确保入站请求未被拦截

验证域名解析是否正确

服务器响应问题

确保服务器在 15 秒内返回 HTTP 200 状态码

检查服务器日志中是否有错误信息

确认接口路径和 HTTP 方法是否正确

内容格式问题

确认收到的 POST 请求体为 JSON 格式

检查 Content-Type 是否为 application/json

验证 JSON 解析是否正确

替代方案

如果您无法使用回调机制，也可以采用轮询方式：

轮询验证短句结果

使用获取验证短句接口定期查询任务状态。建议每 3-30 秒查询一次。

Suno Voice 验证短句回调

回调机制概述#

回调时机#

回调方式#

回调请求格式#

状态码说明#

code（整数，必填）#

msg（字符串，必填）#

data.taskId（字符串，必填）#

data.validateInfo（字符串）#

data.status（字符串）#

data.errorCode（整数）#

data.errorMessage（字符串）#

回调接收示例#

最佳实践#

常见问题排查#

替代方案#

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

code（整数，必填）

msg（字符串，必填）

data.taskId（字符串，必填）

data.validateInfo（字符串）

data.status（字符串）

data.errorCode（整数）

data.errorMessage（字符串）

回调接收示例

最佳实践

常见问题排查

替代方案