init → complete, 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
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 reachesawaiting status, data contains:
See Init API Reference →
Step 2: Complete — Upload Verification Recording & Create Persona
After the user readsphrase_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
See Complete API Reference →
Complete Example
Error Codes
Important Notes
- Single taskId lifecycle: Init and complete use the same
taskId— poll one task throughout the entire flow. awaitingstatus: After init completes, the task status isawaiting(notsuccess). Thedatafield containsphrase_textfor the user to read.- 30s time limit: You must call
completewithin 30 seconds after the task reachesawaiting. Exceeding this causesVP_USER_TIMEOUT. - Simplified parameters:
completeonly needstaskId+ 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:
languagedetermines 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.