> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno Voice 验证短句回调

> Suno Voice 验证短句任务完成或失败时，通过 POST 回调接收结果。

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

## 回调机制概述

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

### 回调时机

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

### 回调方式

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

## 回调请求格式

<CodeGroup>
  ```json 验证短句生成完成回调 theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "taskId": "xxx_task_id_xxx",
      "validateInfo": "请清晰录制这段验证短句。",
      "status": "wait_validating",
      "errorCode": 0,
      "errorMessage": ""
    }
  }
  ```

  ```json 验证短句生成失败回调 theme={null}
  {
    "code": 400,
    "msg": "Validation phrase generation failed",
    "data": {
      "taskId": "xxx_task_id_xxx",
      "validateInfo": "",
      "status": "processing_validate_fail",
      "errorCode": 500,
      "errorMessage": "Failed to generate validation phrase"
    }
  }
  ```
</CodeGroup>

## 字段说明

<ParamField path="code" type="integer" required>
  回调状态码。`200` 表示成功，非 200 表示任务失败或处理异常。
</ParamField>

<ParamField path="msg" type="string" required>
  回调状态消息。
</ParamField>

<ParamField path="data.taskId" type="string" required>
  验证短句生成接口返回的任务 ID。
</ParamField>

<ParamField path="data.validateInfo" type="string">
  验证短句文本。当 `status` 为 `wait_validating` 时返回。
</ParamField>

<ParamField path="data.status" type="string" required>
  任务状态。常见回调状态包括 `wait_validating`、`processing_validate_fail` 和 `fail`。
</ParamField>

<ParamField path="data.errorCode" type="integer">
  任务失败时返回的错误码。
</ParamField>

<ParamField path="data.errorMessage" type="string">
  任务失败时返回的详细错误信息。
</ParamField>

## 接收回调示例

```javascript Node.js theme={null}
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);
```

## 相关接口

<Card title="获取验证短句" icon="lucide-search" href="/cn/suno-api/suno-voice-validate-info">
  使用 taskId 手动查询同一任务状态
</Card>