Create a new voice character

The request body accepts two encodings: application/json (prompt / avatar as data URLs) or multipart/form-data (prompt / avatar as files, train_params / extra_params / vcover as JSON strings, booleans as "true" / "false"). Multipart allows at most 2 files of 100 MB each (exceeded → UPLOAD_TOO_LARGE); the reference audio itself is capped at 100 MB (exceeded → VOICE_PROMPT_TOO_LARGE) and must contain at least 3 seconds of speech.

modelVersion defines the capability envelope. It defaults to v3.0 when omitted — not to the newest v4.0. Recommended values:

v3.0 — professional cloning is supported; if the account has not been granted professional-cloning access the call returns 403 — contact sales to enable it. A professional clone must also name a concrete language; auto is rejected

v4.0 (Preview) — controllable (instruct) path only, so lora, isTest and vcover are all rejected

Illegal values return VOICE_MODEL_VERSION_INVALID — they are not silently downgraded.

WARNING

Capability mismatches may share the code VALIDATION_BAD_PARAMS; tell them apart by message.

The returned voice is not necessarily usable yet: status may still be creating — poll GET /api/voice/{id} until it becomes pending. Professional clones come back as lora-pending / lora-awaiting and only reach lora-success once training finishes.

May return RATE_LIMIT_* (HTTP 429). Read Retry-After and retry with exponential backoff. See the "Errors" document.

Professional-cloning quota is consumed before the voice is created and further processing begins, and is refunded automatically if any later step fails.

INFO

Deprecated alias: /api/tts/voice. See the site document "Versions and migration".

INFO

A professional-clone (lora) submission goes straight into training.

INFO

See the Errors document for the full code reference. Always use the X-Vocu-App-Request-Id response header when troubleshooting.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

Example

{
    "name": "Brandi Grady",
    "prompt": "data:audio/wav;base64,X2WDzbOHAPf88clAqELykihJsChXfWwV1C4Oqx9nFyZp82bzq4EOcrzuCWAIiU9AOovOJRMQRJjkslpXTJuNf5D8wfdrfCRM1JHqktqEDCeFVgZhfl2pVbcRyWDVEybArGf4KCYDIJC9DlpdxZIqXDBOPIznQ5RuyACOKx9HN0zzfVtKeAbW7ujKTiRR3DiHsTrWq7g11bLKznC5Lzjg0cEN0bPDnZdEvs0acuOzRFSQCAoweCyCrkBJv0KM9EjOyRlvsGby7Zqg4odsDqok6NmhN0wpmcoUO7cHjoVitVtnBHtjrf3SpnQ2YhRyEDnWql5i12thBqF6lpZ2j8RjxW4HYBkcdSRkJxZC1QzHdozblKfbkaRJ26Z3Rz2t2mY98pxNUmpHiJD8PWSTJbg3q0YLXu2pFFZ729XN2aGTRA3imzfsjE6vNtN4j8PM7HieHw9yHhX15W4QPJyrTtNVdVj8O3eVYmNlQmwiMNlYfdU2tpZfdxNE",
    "modelVersion": "v3.0",
    "language": "fr",
    "description": "founder",
    "avatar": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEuMSIgYmFzZVByb2ZpbGU9ImZ1bGwiIHdpZHRoPSIzMzQ4IiBoZWlnaHQ9IjE5NjIiPjxyZWN0IHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGZpbGw9IiNjNzJlYzMiLz48dGV4dCB4PSIxNjc0IiB5PSI5ODEiIGZvbnQtc2l6ZT0iMjAiIGFsaWdubWVudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSJ3aGl0ZSI+MzM0OHgxOTYyPC90ZXh0Pjwvc3ZnPg==",
    "vocalFilter": false,
    "lora": "71b6711b-9c03-47f4-acfb-bd94dadbaed8"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Successfully created voice character

application/json

Voice created. Note that status may still be creating / lora-pending — poll to confirm readiness

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "e4296465-a999-4869-b103-09dc4506bdf1",
        "idForGenerate": "894b9cf3-d0dc-41c9-91dc-2b4947f588d6",
        "name": "Huan Wei",
        "status": "pending",
        "metadata": {
            "avatar": "https://loremflickr.com/1688/727?lock=1030955216131236",
            "description": "A very capable coach",
            "prompts": [
                {
                    "id": "default",
                    "name": "Default Style",
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/062326/734689-playback-kg1wvu.mp3"
                }
            ]
        }
    }
}

🟠400Bad request

🟠401Unauthorized

🟠403Forbidden

🟠413Payload too large

🟠429Rate limited

🔴500Server error

🔴503Temporarily unavailable