Reset a style and reprocess its reference audio

Discard every derived artifact of this style and re-run reference-audio processing with the new processing switches. The original uploaded audio is not affected.

Fields cleared (routes/voice/prompt.js:187-215): upstream style binding, preview audio, transcription text, audio duration, base speech rate;
v4.0 voices additionally clear the processed reference clip and instruct annotation (for v4.0 those two are the actual "style substance").

enhance and vocalFilter are unconditionally rewritten to the passed values (omitted is treated as false); it is not "keep existing if omitted".

Reset takes effect asynchronously: this endpoint only clears fields and returns immediately; the actual reprocessing is lazily triggered on the next generate / preview.

This endpoint does not validate whether promptId exists: passing a non-existent style ID still returns 200, with no fields modified.

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}/reset — 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

重置成功，返回清空派生字段后的完整语音角色对象

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": false,
                    "language": "zh",
                    "flags": [
                        "20250227-vcb",
                        "v3:20250828-vfa"
                    ],
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/default-origin.wav",
                    "vocalFilter": false
                }
            ]
        }
    }
}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠404记录不存在

🟠409

🟠429

🔴500服务器错误

Reset a style and reprocess its reference audio

Request

Request Code Samples

Responses