Synchronous real-time voice generation

This endpoint has two independent admission gates and is the only public endpoint that mandates an API key:

An API key is required (Authorization: Bearer sk-...). Calling with a logged-in session token returns 403 TTS_SESSION_TOKEN_NOT_ALLOWED.

The account must be on a paid plan, otherwise 403 TTS_PAID_ONLY.

INFO

API keys are returned in plaintext only at creation time. See the "Authentication" document.

DANGER

When over concurrency budget the call does not fail immediately; it may wait about 330 seconds before RATE_LIMIT_CONCURRENT. Set the client HTTP timeout above 330 seconds. See the "Text to speech" document.

Limits are quota.syncBaseConcurrent + quota.syncPaidConcurrent on GET /api/account/info.

Three mutually exclusive modes (chosen by which fields you send):

input_audio → voice conversion. TTS fields are silently cleared; the URL must come from POST /api/tts/upload-audio or you get TTS_INPUT_AUDIO_INVALID.

instruct_mode: true → controllable synthesis, no SRT.

neither → regular TTS. Unsupported voices return VOICE_INSTRUCT_PATH_ONLY.

Invalid values are not always errors: short language codes, out-of-range speechRate / seed, and all-zero emo_switch are dropped. Only a malformed emo_switch (length ≠ 5) is 400. See the "Text to speech" document.

Output is MP3. There is no format / bitrate / sampleRate parameter. See the "Audio and formats" document. Billing is charged on success (credit_used / billing).

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

{
    "voiceId": "6765cf49-c73a-4fae-985d-806b782ec4f2",
    "text": "Hello there, the weather is really nice today!",
    "promptId": "default",
    "preset": "balance",
    "break_clone": true,
    "language": "auto",
    "vivid": false,
    "emo_switch": [
        0,
        0,
        0,
        0,
        0
    ],
    "speechRate": 1,
    "flash": false,
    "stream": false,
    "seed": -1,
    "srt": false
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Audio successfully generated

application/json

Synthesis complete; data.audio is the audio URL, or a pullable stream URL when stream=true

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "6e2818f1-0817-4425-896b-13fed645a2ce",
        "audio": "https://storage.vocu.ai/generate/f6d422f8-0d1c-4a26-8ee3-a255eb25ebeb/12a2dcfd-9aa8-42b6-bd47-5f6fa3a235cc.mp3",
        "streamUrl": "https://storage.vocu.ai/generate/d590af82-4889-4ef2-91a5-1021022c85b6/stream.mp3?auth=1d105b1b-762a-4e86-8b3c-6c8c2d41b0fe",
        "credit_used": 44
    }
}

🟠400Bad request

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠409Conflict

🟠429Rate limited

🔴500Server error

🔴503Temporarily unavailable