Create Asynchronous Voice Generation Task

How this differs from /api/tts/simple-generate: this endpoint returns the job as soon as it is submitted, supports multi-segment contents, mixed content types and SRT subtitles, and requires neither an API key nor a paid plan. simple-generate is the single-segment synchronous path with much stricter admission.

Three mutually exclusive request shapes — mixing them returns 400 VALIDATION_CONFLICT:

contents — an array of content blocks, each declaring its type (text / audio / sfx / music / scene / custom_audio / stem_separation)

text + splitter — the server compiles them into contents; both must be supplied together

text + splitterId — the same, but the split rules are loaded from a saved config; splitterId and splitter cannot both be sent

sync does not mean "wait for the audio": it only waits for the job to reach processing, for at most 90 seconds, then returns STREAM_TIMEOUT (note that this code maps to 400, not 408). You still fetch the audio by polling GET /api/tts/generate/{id} until status === 'generated'.

Validation strictness is the opposite of simple-generate: nearly every invalid value inside contents collapses into one 400 TTS_CONTENTS_INVALID with no indication of which field was at fault — including a language outside the synthesis value list (a hard error here, unlike the silent drop in simple-generate), an emo_switch that is not exactly 5 values in 0–10, an out-of-range mos_score or sfx_length, and audio URLs not uploaded through this platform. Expect to bisect your payload when debugging.

WARNING

Each type has its own list of usable parameters, and keys outside that list are silently dropped without an error — see the description of the contents[].type request field for the exact lists.

May return RATE_LIMIT_* (HTTP 429). Read Retry-After and retry with exponential backoff. See the "Errors" document. Paid accounts' jobs are processed with higher priority.

Credits are frozen before submission rather than deducted, and unfrozen if the job fails. SRT subtitles are a paid feature: srt: true from a free account is silently forced to false.

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

{
    "contents": [
        {
            "voiceId": "46cc9a76-acd7-4af7-a13a-f8b1408b1848",
            "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
        },
        {
            "voiceId": "b8511ce5-0860-4703-9be6-db6017668227",
            "text": "Yes, yes, I think so too, it's perfect for going out!",
            "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
        },
        {
            "voiceId": "89506c35-c207-458b-95e1-3235cc2f3b6e",
            "text": "What are you guys talking about? Oh, you're talking about the weather!",
            "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

🟢200Asynchronous generation task successfully created

application/json

Job created with data.status = pending (or processing when sync=true); poll the job detail endpoint for the audio

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "021e4a43-0898-4942-abd9-c9f6a4ff61d3",
        "userId": "f582d32e-a20f-406d-bbb5-534960d9aa89",
        "status": "generated",
        "type": "vocu-neural-voice-001",
        "metadata": {
            "contents": [
                {
                    "voiceId": "bcbaf249-3a92-4cca-b53c-42d29e745751",
                    "text": "Fresh mixed greens tossed with mustard-rubbed pigeon, fresh chillies, and a light dressing.",
                    "audio": "https://storage.vocu.ai/generate/7d06aeec-d9a6-4ccb-9cc0-737c76559c95/05137b6a-34b3-406a-a8d1-5ad488efcc82-1.mp3",
                    "generatedAt": "1961-07-30T23:58:39.042Z",
                    "preset": "balance",
                    "break_clone": true,
                    "language": "auto",
                    "vivid": false,
                    "emo_switch": [
                        0,
                        0,
                        0,
                        0,
                        0
                    ],
                    "speechRate": 1,
                    "flash": false,
                    "stream": false,
                    "seed": -1
                },
                {
                    "voiceId": "6c76d3ca-913b-4b68-b233-dac212c4b63b",
                    "text": "A special blue strawberries from Puerto Rico. To support the strong flavor it is sided with a tablespoon of german chamomile.",
                    "audio": "https://storage.vocu.ai/generate/aa8f08ce-351b-4027-a2b7-892bbd3b7bfa/15eefb54-222a-4cea-836d-3cb54d8746cf-2.mp3",
                    "generatedAt": "1956-09-06T15:51:47.576Z",
                    "preset": "balance",
                    "break_clone": true,
                    "language": "auto",
                    "vivid": false,
                    "emo_switch": [
                        0,
                        0,
                        0,
                        0,
                        0
                    ],
                    "speechRate": 1,
                    "flash": false,
                    "stream": false,
                    "seed": -1
                },
                {
                    "voiceId": "c17911c5-4ef2-4145-bd62-e58535ddad4a",
                    "text": "Juicy turkey, grilled to your liking and drizzled with a bold celery sauce, served alongside roasted green pepper.",
                    "audio": "https://storage.vocu.ai/generate/3dfc1bbc-c4c0-4621-9a9e-87ae9c1019bd/ca4a2d33-2060-47a8-96d3-6f1e1f76b2c1-3.mp3",
                    "generatedAt": "2020-02-28T03:50:49.626Z",
                    "preset": "balance",
                    "break_clone": true,
                    "language": "auto",
                    "vivid": false,
                    "emo_switch": [
                        0,
                        0,
                        0,
                        0,
                        0
                    ],
                    "speechRate": 1,
                    "flash": false,
                    "stream": false,
                    "seed": -1
                }
            ],
            "characters": 66,
            "voices": [
                {
                    "id": "8714ca7b-c28a-4710-accb-3a2baabcfcba",
                    "name": "Shannon Bins",
                    "status": "lora-success",
                    "metadata": {
                        "avatar": "https://loremflickr.com/3245/3989?lock=908384138534414",
                        "description": "business owner, singer, writer",
                        "prompts": [
                            {
                                "id": "2c1f0fa9-9ee2-4fcc-9bee-0fcea6ed7369",
                                "name": "dark",
                                "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/406938/361072-playback-8oz3ag.mp3",
                                "playBackAudio": "https://storage.vocu.ai/prompt/480161/795831-playback-rucs5d.mp3",
                                "description": "those emotional style",
                                "language": "auto",
                                "vocalFilter": true
                            }
                        ]
                    },
                    "version": "v3.0",
                    "from": "market"
                }
            ],
            "isPremium": false,
            "audio": "https://storage.vocu.ai/generate/fc036254-844e-4ff3-bff8-7ae4ef61a099/a8e005ea-8f8f-4f90-ae0b-972567236361-merged.mp3",
            "generatedAt": "1963-06-10T13:23:07.949Z",
            "srt": false
        }
    }
}

🟠400Bad request

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠409Conflict

🟠429Rate limited

🔴500Server error

🔴503Temporarily unavailable