跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt

Use this file to discover all available pages before exploring further.

当提交验证短句任务并传入 callBackUrl 后，系统会在任务进入最终状态时向您的回调地址发送 POST 请求。

​
回调机制概述

生产环境建议使用回调，减少对验证短句查询接口的轮询。

​
回调时机

  • 验证短句生成完成，等待用户录制验证音频
  • 验证短句生成失败
  • 任务处理过程中发生错误

​
回调方式

  • HTTP 方法：POST
  • Content Type：application/json
  • 超时时间：15 秒

​
回调请求格式

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx",
    "validateInfo": "请清晰录制这段验证短句。",
    "status": "wait_validating",
    "errorCode": 0,
    "errorMessage": ""
  }
}

​
字段说明

​
code
integer
必填
回调状态码。200 表示成功，非 200 表示任务失败或处理异常。
​
msg
string
必填
回调状态消息。
​
data.taskId
string
必填
验证短句生成接口返回的任务 ID。
​
data.validateInfo
string
验证短句文本。当 status 为 wait_validating 时返回。
​
data.status
string
必填
任务状态。常见回调状态包括 wait_validating、processing_validate_fail 和 fail。
​
data.errorCode
integer
任务失败时返回的错误码。
​
data.errorMessage
string
任务失败时返回的详细错误信息。

​
接收回调示例

Node.js
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;

  if (code === 200 && data.status === 'wait_validating') {
    console.log('验证短句已生成:', data.taskId, data.validateInfo);
  } else {
    console.error('验证短句任务失败:', msg, data.errorMessage);
  }

  res.status(200).json({ status: 'received' });
});

app.listen(3000);

​
相关接口

获取验证短句

使用 taskId 手动查询同一任务状态