Generate a voice preview from a text description

Generate preview audio for an entirely new voice from a natural-language description (e.g. "a mature male voice around thirty, slightly slow, a bit raspy").

This endpoint only produces a temporary session; it does not create a voice character. After you are satisfied you must call the "confirm voice design" endpoint to persist it as a real voice.

Session mechanism

On success a sessionId is returned; the corresponding session data lives in Redis with a 1-hour TTL (modules/voiceFactory.js:42).

After expiry, calling confirm returns 404 VOICE_DESIGN_SESSION_EXPIRED.

Sessions are bound to the user and cannot be used across accounts.

After a successful confirm the session is deleted immediately; the same sessionId cannot be confirmed twice (the second time is likewise VOICE_DESIGN_SESSION_EXPIRED).

Quota and billing

Each user gets 10 free calls per day (UTC+8); beyond that each call costs 100 credits (modules/voiceFactory.js:44-45).

When the free quota is exhausted and credits are insufficient, 403 is returned, internal sub-code BILLING_DESIGN_QUOTA_EXCEEDED,
the HTTP body's code is the parent code BILLING_QUOTA_EXCEEDED (modules/errorCodes.js:300).

Call the "query voice-design quota" endpoint to inspect remaining count and reset time in advance.

Concurrency control

Each user has 1 design slot by default (configurable per user). When slots are full the request queues for up to 5 minutes;
only when the queue exceeds 10 people or the wait times out is 429 RATE_LIMIT_CONCURRENT returned (modules/voiceFactory.js:86-128).
Response time for this endpoint can therefore be substantially longer than the generation itself; clients should relax their timeout.

Content safety

Both instruct and the model-produced text go through content-safety checks (admin / enterprise roles skip).
A block returns SAFETY_CONTENT_REJECTED; failure of the check service itself returns SAFETY_CHECK_FAILED.

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

试听生成成功，sessionId 用于后续确认

Bodyapplication/json

Example

{
    "status": 200,
    "data": {
        "sessionId": "d52a86f1-40cb-4e73-9b18-27ca6e0f5d94",
        "previewAudioUrl": "https://storage.vocu.ai/voice-design/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/d52a86f1-40cb-4e73-9b18-27ca6e0f5d94.wav",
        "text": "你好，很高兴认识你，希望我们合作愉快。"
    }
}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠429

🔴500服务器错误

Generate a voice preview from a text description

Session mechanism#

Quota and billing#

Concurrency control#

Content safety#

Request

Request Code Samples

Responses

Session mechanism

Quota and billing

Concurrency control

Content safety