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 metadata JSON stored in the database fails to parse (routes/generate/tts.js:530-535); that is server-side data corruption, classified as report-tier 500.

Error responses take the shape { status, code, message, requestId? }. code is always the parent code — sub codes only change message and never appear in the body. requestId is present only on reportable-tier errors, so use the X-Vocu-App-Request-Id response header when troubleshooting (it is written unconditionally on every response). See the "Errors" document for the full code reference.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Responses

🟢200成功

application/json

创建成功

Bodyapplication/json

Example

{
    "status": 200,
    "data": {
        "id": "3f2a1b6c-8d4e-4f27-9a10-5c7e2d81b043",
        "name": "双人对话配置",
        "config": {
            "<角色A>": {
                "voiceId": "9d7f2e14-5b30-4a6c-8e91-c2340af6b7d5",
                "speechRate": 1
            },
            "<角色B>": {
                "voiceId": "b81c04a7-6e2f-4d15-93a8-70fe1c6d5382",
                "speechRate": 1
            },
            "[语速加快:1.2]": {
                "speechRate": 1.2
            }
        },
        "createdAt": "2026-08-12T09:31:44.000Z",
        "updatedAt": "2026-08-18T02:07:11.000Z"
    }
}

🟠400请求有误

🟠401没有权限

🟠429

🔴500服务器错误

Create a splitter configuration

Request

Request Code Samples

Responses