Set a style as the default style

Promote the specified style to this voice character's default style.

This is an ID swap, not merely a sort change (routes/voice/prompt.js:132-146):

The target style is removed from the list;

The style that was originally first is assigned a new random UUID;

The target style is inserted at the front, and its ID is rewritten to the fixed string default.

Therefore a caller-cached "original default style ID" (default) becomes invalid after the call — it now points at the newly promoted style;
and the demoted former default receives an entirely new UUID. Rebuild your local ID mapping from prompts in the response after calling.

Calling this endpoint on a style that is already default is idempotent.

Ownership and status checks (modules/routeHelpers.js:254-280, modules/voiceFactory.js:257-270):

Voice does not exist, does not belong to the current user, or has been soft-deleted → 404 VOICE_NOT_FOUND (the three cases are not distinguished)

status = creating → 409 VOICE_CREATING

status = failed → 400 VOICE_CREATE_FAILED

from != upload (e.g. a market-purchased / community-imported voice) → 403 AUTH_FORBIDDEN

Lazy version migration has not finished → 500 SYSTEM_INTERNAL_ERROR (retryable)

Legacy alias: /api/tts/voice/{id}/prompt/{promptId}/default — still supported for backward compatibility; use the primary path for new integrations.

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

设置成功，返回更新后的完整语音角色对象（prompts[0].id 恒为 default）

Bodyapplication/json

Example

{
    "status": 200,
    "data": {
        "id": "7c3d9a12-5e84-4b06-9f21-8ad3e6b40c57",
        "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
                }
            ]
        }
    }
}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠404记录不存在

🟠409

🟠429

🔴500服务器错误

Set a style as the default style

Request

Request Code Samples

Responses