Suno Voice Generation Callbacks

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

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

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 custom voice generation API.

string

Generated custom voice ID. Returned when status is success.

string

required

Task status. Common callback statuses are success, 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-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

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

Suno Voice Generation Callbacks

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Field Description

Receiving Callbacks

Get Custom Voice Record

​Callback Mechanism Overview

​Callback Timing

​Callback Method

​Callback Request Format

​Field Description

​Receiving Callbacks

​Related Endpoint

Get Custom Voice Record

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Field Description

Receiving Callbacks

Related Endpoint