Skip to main content

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.

When you submit a custom voice generation task with callBackUrl, the system sends a POST request to your callback URL when the task completes.

​
Callback Mechanism Overview

The callback contains the generated voiceId when custom voice creation succeeds.

​
Callback Timing

  • Custom voice created successfully
  • Voice verification or creation failed
  • Error occurred during task processing

​
Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout: 15 seconds

​
Callback Request Format

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

​
Field Description

​
code
integer
required
Callback status code. 200 indicates success; non-200 values indicate task failure or processing error.
​
msg
string
required
Status message describing the callback result.
​
data.taskId
string
required
Task ID returned by the custom voice generation API.
​
data.voiceId
string
Generated custom voice ID. Returned when status is success.
​
data.status
string
required
Task status. Common callback statuses are success, processing_validate_fail, and fail.
​
data.errorCode
integer
Error code returned when the task fails.
​
data.errorMessage
string
Detailed error message returned when the task fails.

​
Receiving Callbacks

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('Custom voice ready:', data.voiceId);
  } else {
    console.error('Custom voice task failed:', msg, data.errorMessage);
  }

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

app.listen(3000);

Get Custom Voice Record

Query the same voice generation task manually with taskId