docs.api.box
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
Support
Suno API
Common APIFile Upload API
Suno API
Common APIFile Upload API
  1. Suno Voice
  • API.box Documentation
  • Quick Start
  • Generate Music
    • Music Generation Callbacks
    • Music Extension Callbacks
    • Upload and Cover Audio Callbacks
    • Upload and Extend Audio Callbacks
    • Add Instrumental Callbacks
    • Add Vocals Callbacks
    • Music Cover Generation Callbacks
    • Replace Music Section Callbacks
    • Generate Music
      POST
    • Extend Music
      POST
    • Upload And Cover Audio
      POST
    • Upload And Extend Audio
      POST
    • Add Instrumental
      POST
    • Add Vocals
      POST
    • Get Music Generation Details
      GET
    • Recovery Audio
      POST
    • Get Recovery Audio Details
      GET
    • Get Timestamped Lyrics
      POST
    • Boost Music Style
      POST
    • Generate Music Cover
      POST
    • Replace Music Section
      POST
    • Get Music Cover Details
      GET
    • Generate Persona
      POST
    • Generate Mashup
      POST
  • Suno Voice
    • Suno Voice Validation Phrase Callbacks
    • Suno Voice Generation Callbacks
    • Suno Voice Regenerate Phrase Callbacks
    • Suno Voice Generate Verification Phrase
      POST
    • Suno Voice Get Verification Phrase
      GET
    • Suno Voice Create Custom Voice
      POST
    • Suno Voice Get Custom Voice Record
      GET
    • Suno Voice Regenerate Verification Phrase
      POST
    • Suno Voice Check Availability
      POST
  • Lyrics Generation
    • Lyrics Generation Callbacks
    • Generate Lyrics
    • Get Lyrics Generation Details
  • Generate Sounds
    • Generate Sounds
  • WAV Conversion
    • WAV Format Conversion Callbacks
    • Convert to WAV Format
    • Get WAV Conversion Details
  • Vocal Removal
    • Audio Separation Callbacks
    • MIDI Generation Callbacks
    • Vocal and Instrument Separation
    • Get Audio Separation Details
    • Generate MIDI from Audio
    • Get MIDI Generation Details
  • Music Video Generation
    • Music Video Generation Callbacks
    • Create Music Video
    • Get Music Video Details
  • Generate Speech
    • Generate Speech
  1. Suno Voice

Suno Voice Generation Callbacks

Receive POST callbacks when a Suno Voice custom voice task succeeds or fails.
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#

Custom Voice Ready Callback
Custom Voice Failed Callback
{
  "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

Related Endpoint#

Get Custom Voice Record
Query the same voice generation task manually with taskId
Previous
Suno Voice Validation Phrase Callbacks
Next
Suno Voice Regenerate Phrase Callbacks
Built with