Create New Template

POST

https://v1.vocu.ai/api/template

A template stores the structure of a multi-speaker script, not concrete voice bindings.

Each voiceId inside contents is rewritten to a 1-based index on save (stored as metaVoiceId): identical voiceId values map to the same index, and the special value "0" maps to null. The original voice ids are not stored, which is what makes a template portable across accounts — but it also means reading it back cannot tell you which voices you originally used, so they must be re-assigned before generating.

name and contents are both required; omitting either returns 400 VALIDATION_MISSING_FIELD with detail.field naming the missing one. description is optional and is stored in metadata.description.

Names are not checked for uniqueness — creating the same name twice simply yields two independent records.

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": "Food Introduction",
    "description": "Generation template containing various food introductions",
    "contents": [
        {
            "voiceId": "b32c9ae9-845f-4627-ab1e-3444d8d880fc",
            "text": "A bowl of warm Huizhou cuisine soup, made with fresh tuna and seasoned with traditional spices, very fragrant."
        },
        {
            "voiceId": "a518fcf8-2eff-44f3-95bd-53ba5668bcf0",
            "text": "A delightful fruit tart, blending juicy pumpkin and sweet melon in a buttery crust, finished with a hint of bell pepper for flavor."
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://v1.vocu.ai/api/template' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Food Introduction",
    "description": "Generation template containing various food introductions",
    "contents": [
        {
            "voiceId": "b32c9ae9-845f-4627-ab1e-3444d8d880fc",
            "text": "A bowl of warm Huizhou cuisine soup, made with fresh tuna and seasoned with traditional spices, very fragrant."
        },
        {
            "voiceId": "a518fcf8-2eff-44f3-95bd-53ba5668bcf0",
            "text": "A delightful fruit tart, blending juicy pumpkin and sweet melon in a buttery crust, finished with a hint of bell pepper for flavor."
        }
    ]
}'

Responses

🟢200Template Created Successfully

application/json

Template created (voices in contents are replaced by metaVoiceId indices)

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "77f54dab-6e96-4c11-afac-2db3f99e4b02",
        "name": "Food Introduction",
        "contents": [
            {
                "metaVoiceId": 22,
                "text": "Fresh mixed salad, featuring black pepper marinated pork and broccoli, drizzled with a light dressing."
            },
            {
                "metaVoiceId": 31,
                "text": "Our golden duck, slow-cooked to perfection, served with steamed spinach and a rich gravy."
            }
        ],
        "metadata": {
            "metaVoiceId": 81,
            "description": "Template containing various food introductions"
        },
        "userId": "b3ed390b-e26f-4657-8458-67a8290514a1",
        "from": "self",
        "originId": "2e4ad6df-900d-4843-9d65-1a385552b12d"
    }
}

🟠400Bad request

🟠401Unauthorized

🟠429Rate limited

Modified at 2026-08-23 09:24:46

Get Template Details with Specified ID

Update Template with Specified ID