> ## 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>
  自建音色创建成功时，回调中会包含生成的 `voiceId`。
</Info>

### 回调时机

* 自建音色创建成功
* 音频验证或音色创建失败
* 任务处理过程中发生错误

### 回调方式

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

## 回调请求格式

<CodeGroup>
  ```json 自建音色生成完成回调 theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "taskId": "xxx_task_id_xxx",
      "voiceId": "voice_xxx",
      "status": "success",
      "errorCode": 0,
      "errorMessage": ""
    }
  }
  ```

  ```json 自建音色生成失败回调 theme={null}
  {
    "code": 400,
    "msg": "Voice generation failed",
    "data": {
      "taskId": "xxx_task_id_xxx",
      "voiceId": "",
      "status": "fail",
      "errorCode": 500,
      "errorMessage": "Verification audio did not match the 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.voiceId" type="string">
  生成的自建音色 ID。当 `status` 为 `success` 时返回。
</ParamField>

<ParamField path="data.status" type="string" required>
  任务状态。常见回调状态包括 `success`、`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-generate-callback', (req, res) => {
  const { code, msg, data } = req.body;

  if (code === 200 && data.status === 'success') {
    console.log('自建音色已生成:', data.voiceId);
  } else {
    console.error('自建音色任务失败:', msg, data.errorMessage);
  }

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

app.listen(3000);
```

## 相关接口

<Card title="获取自建音色记录" icon="lucide-list-checks" href="/cn/suno-api/suno-voice-record-info">
  使用 taskId 手动查询同一音色生成任务
</Card>