Suno Voice 生成回调

当 Suno Voice 自建音色生成完成时，系统会调用此回调。

自建音色的最终结果会推送到验证短句任务（即调用 create-voice 时传入其 taskId 的那个任务）的 callBackUrl。create-voice 本身会立即返回 success，这只表示请求已受理。Voice ID 就是验证短句任务的 taskId。

回调机制概述

Webhook安全说明

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

回调时机

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

音色生成成功

音色生成失败

音色生成处理过程中发生错误

回调方式

HTTP方法：POST

内容类型：application/json

超时设置：15秒

回调请求格式

验证短句任务进入最终状态时，系统将以如下格式向该任务的callBackUrl发送POST请求：

成功回调

失败回调

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx",
    "status": "success",
    "errorCode": null,
    "errorMessage": ""
  }
}

状态码说明

code（整数，必填）

回调状态码，表示任务处理结果：

状态码	说明
200	成功 - 音色已生成
500	失败 - 音色生成失败或内部处理出错

msg（字符串，必填）

状态消息，提供详细的状态描述。

data.taskId（字符串，必填）

验证短句任务的任务ID，即 Voice ID：在生成音乐接口中把它填入 persona_id，并设置 persona_model: "voice_persona"。

data.status（字符串）

任务最终状态。

状态	说明
success	音色已可用
fail	录音未通过校验

data.errorCode（整数）

错误码。任务成功时通常为null。

data.errorMessage（字符串）

详细错误信息。任务成功时通常为空。

回调接收示例

以下是主流编程语言接收回调的示例代码：

Node.js

Python

PHP

最佳实践

回调地址配置建议

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

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

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

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

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

保存 Voice ID：保存验证短句任务的 taskId，后续生成时作为 persona_id 使用

重要提醒

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

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

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

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

成功后请及时保存 Voice ID（验证短句任务的 taskId），后续使用该音色生成时需要它

常见问题排查

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

网络连接问题

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

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

验证域名解析是否正确

服务器响应问题

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

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

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

内容格式问题

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

检查Content-Type是否为application/json

验证JSON解析是否正确

Suno Voice 生成回调

回调机制概述#

回调时机#

回调方式#

回调请求格式#

状态码说明#

code（整数，必填）#

msg（字符串，必填）#

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

data.status（字符串）#

data.errorCode（整数）#

data.errorMessage（字符串）#

回调接收示例#

最佳实践#

常见问题排查#

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

code（整数，必填）

msg（字符串，必填）

data.taskId（字符串，必填）

data.status（字符串）

data.errorCode（整数）

data.errorMessage（字符串）

回调接收示例

最佳实践

常见问题排查