Skip to main content
Create a Voice Persona with two free calls: initcomplete, one taskId. This is the free Voice Persona path. Clone Voice (/voices) is the paid one-step wrapper of the same pipeline. Compare in Persona overview. On /generate, always pass persona.is_voice: true and keep the same Suno account.

Workflow

Task Status Flow

After the task reaches awaiting status, you must call complete within 30 seconds (default). If the timeout is exceeded, the task will fail with VP_USER_TIMEOUT and you’ll need to restart from init.

Step 1: Init — Upload Voice & Get Verification Phrase

Upload the user’s voice audio. The system extracts vocals and returns a verification phrase that the user must read aloud.
This is an async task. Poll Get Task Status with the returned taskId. Wait for status to become awaiting (not success).

Request

Polling Result (status: awaiting)

When the task reaches awaiting status, data contains:
Only phrase_text is needed by the user. All other fields are used internally by the system — you do not need to pass them to the complete step.
See Init API Reference →

Step 2: Complete — Upload Verification Recording & Create Persona

After the user reads phrase_text aloud and records it, upload the verification recording using the same taskId to complete voice verification and create the persona.
Uses the same taskId from init. After calling complete, continue polling the same taskId until status becomes success.

Request

No intermediate data (vox_audio_id, phrase_id, etc.) is needed — the system reads them automatically from the init phase.
See Complete API Reference →

Complete Example


Error Codes

Important Notes

The verification recording must clearly contain the full phrase_text content. Incomplete or unclear recordings will cause voice verification to fail.
  • Single taskId lifecycle: Init and complete use the same taskId — poll one task throughout the entire flow.
  • awaiting status: After init completes, the task status is awaiting (not success). The data field contains phrase_text for the user to read.
  • 30s time limit: You must call complete within 30 seconds after the task reaches awaiting. Exceeding this causes VP_USER_TIMEOUT.
  • Simplified parameters: complete only needs taskId + verification recording URL + persona info. All intermediate data is auto-filled by the system.
  • Same account guarantee: Both phases automatically use the same Suno account.
  • Language selection: language determines the verification phrase language. Match the language of the original voice audio for best results.
  • Processing time: Init takes ~20-60s (includes vocal extraction); Complete takes ~10-30s (includes voice verification).
  • Concurrency safety: The system serializes Voice Persona operations per account — concurrent requests from different users won’t interfere.