Create a splitter configuration

Create a reusable splitter configuration. A splitter takes a stretch of text with placeholder markers, splits it into utterances, and binds a voice plus generation parameters to each utterance,
so a multi-character dialogue can be generated in one request.

Working with POST /api/tts/generate

The generate endpoint has two mutually exclusive inputs: splitter (inline configuration object) and splitterId (reference to a saved configuration ID).
The data.id returned here is the value you can pass as splitterId. In splitter mode you must also pass text, and you must not also pass contents.

Configuration validation rules (failure → TTS_SPLITTER_INVALID)

config must be a non-array object.

After stripping the three reserved keys, if there is no placeholder, no fallbackConfig, and no splitterMarks, it is invalid.

Placeholder keys cannot be empty strings; their values must be non-array objects.

If lookupTable is present: it must be a non-array object; each entry must be a non-array object containing a non-empty tags array; tags elements may only be strings or arrays of strings.

If fallbackConfig is present: it must be a non-array object and must contain a string voiceId.

If splitterMarks is present: it must be an array, and every element must be a string of exactly 2 characters.

About TTS_SPLITTER_METADATA_INVALID

This error code is not produced by this CRUD group. It is thrown only when POST /api/tts/generate references a configuration via splitterId
and the stored metadata JSON fails to parse; that is server-side data corruption (HTTP 500).

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/jsonRequired

Example

{
    "name": "string",
    "config": {
        "splitterMarks": [
            "st"
        ],
        "lookupTable": {
            "property1": "string",
            "property2": "string"
        },
        "fallbackConfig": {
            "voiceId": "string"
        },
        "property1": "string",
        "property2": "string"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Created

Bodyapplication/json

Example

{
    "status": 200,
    "data": {
        "id": "3f2a1b6c-8d4e-4f27-9a10-5c7e2d81b043",
        "name": "Two-speaker dialogue configuration",
        "config": {
            "<CharacterA>": {
                "voiceId": "9d7f2e14-5b30-4a6c-8e91-c2340af6b7d5",
                "speechRate": 1
            },
            "<CharacterB>": {
                "voiceId": "b81c04a7-6e2f-4d15-93a8-70fe1c6d5382",
                "speechRate": 1
            },
            "[faster_speech:1.2]": {
                "speechRate": 1.2
            }
        },
        "createdAt": "2026-08-12T09:31:44.000Z",
        "updatedAt": "2026-08-18T02:07:11.000Z"
    }
}

🟠400Bad request

🟠401Unauthorized

🟠429Rate limited

🔴500Server error