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 Create Custom Voice

POST
/api/v1/voice/generate
Generate a reusable Suno custom voice from the user's verification recording.

Usage Guide#

Call this API after the validation phrase is generated and the user has recorded the verification audio.
The validation phrase is the validateInfo text returned by the server. For best voice generation results, have the user record the server-provided phrase in a singing voice rather than plain speech.
Submit the original validation taskId and the verification audio URL in verifyUrl.
Optional metadata such as voiceName, description, style, and singerSkillLevel helps organize and tune the generated voice.
The API returns a taskId; use it to query the final voiceId.
When callBackUrl is provided, the system sends a POST callback when the voice is created or the task fails. The callback URL must be publicly accessible and return HTTP 200 within 15 seconds.

Workflow#

1.
Generate and retrieve the validation phrase.
2.
Record clear verification audio for the phrase; singing is recommended for best voice generation results.
3.
Upload or host the verification audio and pass the URL as verifyUrl.
4.
Submit the voice generation task and store the returned taskId.
5.
Receive voiceId through the record query API or callback when the task succeeds.

Callback#

Custom Voice Generation Callbacks
Learn the callback payload sent when the custom voice is created or the task fails

Developer Notes#

taskId must come from the validation phrase task for the same voice workflow.
verifyUrl should point to the user's recording of the exact validation phrase returned by the server; for best results, recording it in a singing voice is recommended.
After receiving voiceId, use the availability check endpoint before starting generation workflows that depend on the custom voice.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://apibox.erweima.ai/api/v1/voice/generate' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "taskId": "voice_create_001",
    "verifyUrl": "https://example.com/audio/verify_read.mp3",
    "voiceName": "My Voice",
    "description": "created from uploaded voice",
    "style": "Pop, Female Vocal",
    "singerSkillLevel": "beginner",
    "callBackUrl": "https://example.com/callback/suno/voice_create"
}'
Response Response Example
{
    "code": 200,
    "msg": "success",
    "data": {
        "taskId": "xxx_task_id_xxx"
    }
}
Previous
Suno Voice Get Verification Phrase
Next
Suno Voice Get Custom Voice Record
Built with