Generate a voice-character preview clip

Render preview audio for a voice character's styles from a short text. The result is written back to metadata.prompts[].previewAudio,
a record is appended to metadata.previewGenerateHistory, and then the complete voice-character object is returned (not a single URL).

Omitting promptId generates one preview for every style; time scales with the number of styles.

Text length limit: after o200k_base tokenization it must not exceed 70 tokens (not 70 characters); exceeding returns VALIDATION_BAD_PARAMS.

language is strictly validated on this endpoint: only the 10 values auto / zh / en-us / ja / ko / fr-fr / pt / de / es / yue
are accepted (modules/validationConstants.js:3); an illegal value returns 400 VALIDATION_BAD_PARAMS immediately.
This differs from voice-creation / add-style endpoints (POST /api/voice, POST /api/voice/{id}/prompt) — those two run illegal language
through validateLanguageKeepNull and silently downgrade to auto without erroring. Also note it is en-us / fr-fr, not en / fr.

v4.0 voices have no upstream synthesizer; preview is rendered through the instruct pipeline, and neither mode nor vivid takes effect (modules/voiceFactory.js:1065-1106).

Legacy alias: /api/tts/voice/{id}/generatePreview — 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": 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,
                    "previewAudio": "https://storage.vocu.ai/generate/1a6e0c74-93bf-4d28-8f05-6b2e7a1c94d3/1a6e0c74-93bf-4d28-8f05-6b2e7a1c94d3-preview-default.mp3"
                }
            ],
            "previewGenerateHistory": [
                {
                    "text": "今天天气不错，适合出门走走。",
                    "urls": [
                        "https://storage.vocu.ai/generate/1a6e0c74-93bf-4d28-8f05-6b2e7a1c94d3/1a6e0c74-93bf-4d28-8f05-6b2e7a1c94d3-preview-default.mp3"
                    ],
                    "generatedAt": "2026-08-19T11:04:37.000Z",
                    "cost": 14
                }
            ]
        }
    }
}

🟠400请求有误

🟠401没有权限

🟠404记录不存在

🟠409

🟠429

🔴500服务器错误

🔴503服务器故障

Generate a voice-character preview clip

Request

Request Code Samples

Responses