Confirm a voice design and create a voice character

Persist a design / remix session as a real voice character: download the session's preview audio, run the full voice-creation flow at the specified model version, persist, then delete the session.

modelVersion defaults to v3.0 (consistent with POST /api/voice); v4.0 is a strict opt-in.
The value must be one of v2.0 / v3.0 / v4.0, otherwise VOICE_MODEL_VERSION_INVALID (modules/voiceVersion.js:26).

v4.0 capability envelope: no professional cloning / voice cover / test voices; instruct generate path only.
If such a voice is missing its upstream binding, the generate side reports VOICE_INSTRUCT_PATH_ONLY (modules/voiceVersion.js:61-68).

Language is taken from the session itself (the language resolved at design time); this endpoint does not accept a language parameter.

Session one-shot

Session TTL is 1 hour; expired, missing, not owned by the current user, or already confirmed, all return 404 VOICE_DESIGN_SESSION_EXPIRED.

Error-code collapse (important)

Every exception after parameter validation — audio download failure, content-safety block, insufficient quota, upstream character-creation failure —
is uniformly collapsed to 500 SYSTEM_INTERNAL_ERROR (routes/voice/design.js:437-443).
This endpoint will not return SAFETY_* or BILLING_* series error codes; the client cannot learn the concrete failure reason from the response
and must use the X-Vocu-App-Request-Id response header to have the backend investigate.

This endpoint has a single path; there is no /api/tts/voice/... compatibility alias.

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": "e04b7a58-2c91-4f63-8d17-9b5ac6f21e80",
        "name": "成熟男声",
        "status": "pending",
        "from": "upload",
        "version": "v3.0",
        "originId": null,
        "userId": "2f81b40c-9d63-4e17-a5b8-31c7d0e926af",
        "avatar": "https://storage.vocu.ai/avatar/voice/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/7c3d9a12-5e84-4b06-9f21-8ad3e6b40c57.png",
        "createdAt": "2026-07-14T06:22:08.000Z",
        "updatedAt": "2026-08-19T11:04:37.000Z",
        "deletedAt": null,
        "metadata": {
            "description": "三十岁左右的成熟男声，语速偏慢",
            "avatar": "https://storage.vocu.ai/avatar/voice/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/7c3d9a12-5e84-4b06-9f21-8ad3e6b40c57.png",
            "prompts": [
                {
                    "id": "default",
                    "name": "默认",
                    "description": "平稳叙述",
                    "enhance": true,
                    "language": "zh",
                    "flags": [
                        "20250227-vcb",
                        "v3:20250828-vfa"
                    ],
                    "playBackAudio": "https://storage.vocu.ai/prompt/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/default-playback.mp3",
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/default-origin.wav",
                    "baseSpeechRate": 4.6,
                    "voiceDesign": {
                        "instruct": "三十岁左右的成熟男声，语速偏慢，带一点沙哑",
                        "text": "你好，很高兴认识你，希望我们合作愉快。"
                    }
                }
            ]
        }
    }
}

🟠400请求有误

🟠401没有权限

🟠404记录不存在

🟠429

🔴500服务器错误

Confirm a voice design and create a voice character

Session one-shot#

Error-code collapse (important)#

Request

Request Code Samples

Responses

Session one-shot

Error-code collapse (important)