跳转到主要内容

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 请求。

​
回调机制概述

自建音色创建成功时，回调中会包含生成的 voiceId。

​
回调时机

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

​
回调方式

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

​
回调请求格式

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx",
    "voiceId": "voice_xxx",
    "status": "success",
    "errorCode": 0,
    "errorMessage": ""
  }
}

​
字段说明

​
code
integer
必填
回调状态码。200 表示成功，非 200 表示任务失败或处理异常。
​
msg
string
必填
回调状态消息。
​
data.taskId
string
必填
自建音色生成接口返回的任务 ID。
​
data.voiceId
string
生成的自建音色 ID。当 status 为 success 时返回。
​
data.status
string
必填
任务状态。常见回调状态包括 success、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-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);

​
相关接口

获取自建音色记录

使用 taskId 手动查询同一音色生成任务