Skip to main content

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.

When you submit a validation phrase task with callBackUrl, the system sends a POST request to your callback URL after the validation phrase task reaches a terminal state.

​
Callback Mechanism Overview

Use callbacks in production to avoid polling the validation phrase query endpoint.

​
Callback Timing

  • Validation phrase generated and ready for the user to record
  • Validation phrase generation 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",
    "validateInfo": "Please record this validation phrase clearly.",
    "status": "wait_validating",
    "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 validation phrase generation API.
​
data.validateInfo
string
Validation phrase text. Returned when status is wait_validating.
​
data.status
string
required
Task status. Common callback statuses are wait_validating, 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-validate-callback', (req, res) => {
  const { code, msg, data } = req.body;

  if (code === 200 && data.status === 'wait_validating') {
    console.log('Validation phrase ready:', data.taskId, data.validateInfo);
  } else {
    console.error('Validation phrase task failed:', msg, data.errorMessage);
  }

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

app.listen(3000);

Get Verification Phrase

Query the same task status manually with taskId