Suno Voice 生成回调

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

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

回调机制概述

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

Webhook安全说明

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

回调时机

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

验证短句生成成功

验证短句生成失败

验证短句处理过程中发生错误

回调方式

HTTP方法：POST

内容类型：application/json

超时设置：15秒

回调请求格式

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

成功回调

失败回调

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

状态码说明

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（字符串）

回调接收示例

最佳实践

常见问题排查

替代方案