Suno Voice Validation Phrase Callbacks

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": ""
  }
}

{
  "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"
  }
}

Field Description

integer

required

Callback status code. 200 indicates success; non-200 values indicate task failure or processing error.

string

required

Status message describing the callback result.

string

required

Task ID returned by the validation phrase generation API.

string

Validation phrase text. Returned when status is wait_validating.

string

required

Task status. Common callback statuses are wait_validating, processing_validate_fail, and fail.

integer

Error code returned when the task fails.

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

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

Suno Voice Validation Phrase Callbacks

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Field Description

Receiving Callbacks

Get Verification Phrase

​Callback Mechanism Overview

​Callback Timing

​Callback Method

​Callback Request Format

​Field Description

​Receiving Callbacks

​Related Endpoint

Get Verification Phrase

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Field Description

Receiving Callbacks

Related Endpoint