Create a personalized Voice Persona through voice verification. This is a single-task, two-phase process:Documentation Index
Fetch the complete documentation index at: https://docs.mountsea.ai/llms.txt
Use this file to discover all available pages before exploring further.
init (upload voice + get verification phrase) → complete (upload verification recording + create persona). The entire flow uses one taskId.
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
| Field | Type | Required | Description |
|---|---|---|---|
voice_audio_url | string (URL) | Yes | Publicly downloadable URL of the voice audio (WAV/MP3) |
language | string | Yes | Verification phrase language: zh en ja ko es fr de pt ru hi |
vocal_start_s | number | No | Vocal extraction start time (seconds), default: 0 |
vocal_end_s | number | No | Vocal extraction end time (seconds), default: auto-detected |
Polling Result (status: awaiting)
When the task reachesawaiting status, data contains:
| Field | Description |
|---|---|
phrase_text | Verification phrase text — user must read this aloud and record |
phrase_id | Verification phrase ID (internal) |
vox_audio_id | Extracted vocal audio ID (internal) |
voice_recording_id | Recording ID (internal) |
vocal_start_s | Vocal start time (seconds) |
vocal_end_s | Vocal end time (seconds) |
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
| Field | Type | Required | Description |
|---|---|---|---|
taskId | string (UUID) | Yes | The taskId from init (same task) |
verification_audio_url | string (URL) | Yes | User’s verification recording URL (WAV/MP3) |
name | string | Yes | Persona name |
description | string | No | Persona description |
is_public | boolean | No | Whether public (default: false) |
image_s3_id | string | No | Cover image (base64), auto-generated if not provided |
Complete Example
Error Codes
| Code | Error | Description |
|---|---|---|
| 400 | VP_TASK_NOT_FOUND | taskId does not exist or is not a Voice Persona task |
| 400 | VP_INVALID_STATUS | Task status is not awaiting, cannot call complete |
| 408 | VP_USER_TIMEOUT | Timeout waiting for complete after init (default 30s) |
| 409 | VP_SESSION_EXPIRED | Verification session expired, restart from init |
| 500 | VP_LOCK_EXPIRED | Internal lock expired (retry) |
| 503 | VP_NO_DEDICATED_ACCOUNT_AVAILABLE | No dedicated account available |
| 503 | VP_ALL_ACCOUNTS_BUSY | All account queues are full, retry later |
| 504 | VP_ORPHAN_TIMEOUT | Task queuing timeout |
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.