Close a Turbo channel

Actively close a Turbo channel: disconnect the upstream, clean up the Redis record, release the concurrency slot,
and abort any in-progress upstream reconnect. Connected client sockets are closed as well.

Ownership is checked against the Redis channel record, so this is not subject to the process-memory limitation of GET /api/tts/turbo/channel —
a channel created by any process can be closed as long as the record still exists and belongs to the current user.
A missing channel or one that does not belong to the current user always returns TURBO_CHANNEL_NOT_FOUND (the two cases are not distinguished).

The success response has only status, no data field.

WebSocket protocol

Connection

WS path: /socket/tts/turbo/channel/{turboChannelId} (app.js:485 allowlist)

Use the wsUrl from the response directly; it already includes ?auth={32-character static token}

Auth is independent of HTTP Bearer JWT: during upgrade, the auth query is looked up in Redis auth:user:{token} to obtain userId;
failure returns a bare HTTP/1.1 401 Unauthorized (not a JSON error body)

After a successful upgrade the channel ownership is checked again; missing channel record or not owned by the current user → TURBO_CHANNEL_NOT_FOUND;
upstream socket not yet ready → TURBO_RESOURCE_EXHAUSTED (both are sent as an error frame, then the socket is closed immediately)

Optional query binary=1 (or format=binary) enables binary audio mode: audio is delivered as raw PCM16LE binary frames,
no longer wrapped in hex-JSON; empty frames are still utterance boundaries. Default is hex_json mode.

client → server

type	Description
`synthesis_request`	Submit one utterance of text to synthesize. Note the type is named `synthesis_request`, not `speak`
`cancel`	Interrupt the current utterance (barge-in). Instruct channels only; a regular channel returns `VALIDATION_BAD_PARAMS`
`ping`	Heartbeat; the server replies with `pong`
`close_channel`	Actively close the channel and release the concurrency slot. The type is named `close_channel`, not `close`

The data field of synthesis_request differs by channel type:

Regular (zide) channel:

{ text, promptId?, language?, preset?, seed?, speechRate?, emo_switch?, vivid?,
gamble?, post_processing?, infinite_mode?, break_clone?, break_time?, break_float_time?, volume?,
temperature?, top_k?, top_p?, presence_penalty?, frequency_penalty?, repetition_penalty?, min_p? }

— aligned with /api/tts/simple-generate parameters

Instruct channel: { text, language? } only. text may contain {{...}} emotion-control markers;
timbre / emotion parameters do not apply; billing is computed on the text after markers are stripped

server → client

type	Description
`connected`	Client connected successfully. `data` contains the `audio` encoding description; instruct channels additionally include `features`
`audio_chunk`	One audio frame. `data.hex` is hex-encoded PCM16LE @24kHz mono; an empty frame = utterance boundary
`audio_generated`	One utterance finished. `data.audioUrl` is the WAV URL; when `save_audio:false` it is `null` and `saved:false` is present
`audio_generate_failed`	This utterance failed (not billed); the channel stays alive and the client may resend
`cancelled`	Interrupt took effect (instruct channels only)
`pong`	Heartbeat response
`error`	Request-level error; the channel is not closed
`close`	Server is closing the channel (upstream disconnect, graceful process exit, etc.); the socket closes afterwards

WS error body differs from HTTP

WS-side errors are produced by buildSocketErrorBody() (modules/errorCodes.js:379), shaped as:

{ "type": "error", "data": { "status": 400, "code": "VALIDATION_TOO_LONG", "message": "..." } }

Never includes requestId — requestId is injected only by the HTTP response interceptor in app.js; WS does not go through that path.
audio_generate_failed / audio_generated (when upload fails) / close frames use the same data shape.

Common WS error codes: VALIDATION_MISSING_FIELD (missing text), VALIDATION_TOO_LONG (utterance too long),
RATE_LIMIT_CONCURRENT (pending-utterance cap exceeded), RESOURCE_NOT_FOUND (promptId does not exist),
VALIDATION_INVALID_VALUE (illegal emo_switch format), VALIDATION_BAD_PARAMS (payload is not JSON, or cancel sent on a regular channel),
SAFETY_CHECK_FAILED / CONTENT_MODERATION_BLOCKED (text moderation), BILLING_INSUFFICIENT_CREDIT (insufficient balance),
TTS_GENERATE_FAILED (synthesis failed), UPLOAD_FAILED (audio was delivered but WAV upload failed),
SYSTEM_INTERNAL_ERROR / SYSTEM_SHUTTING_DOWN (sent with a close frame).

Limits

The following two caps apply only to instruct channels (mirroring VoiceDesign upstream INSTRUCT_TTS_MAX_TEXT_CHARS /
INSTRUCT_WS_MAX_PENDING_SPEAKS, routes/generate/turbo.js:64-65):

Per-utterance text 8192 characters (TURBO_INSTRUCT_MAX_TEXT_CHARS) — exceeding returns VALIDATION_TOO_LONG

Pending-utterance cap 16 (TURBO_INSTRUCT_MAX_PENDING_SPEAKS) — exceeding returns RATE_LIMIT_CONCURRENT

Regular (zide) channels do not apply these two checks; the upstream decides on its own.

Concurrent channel count is determined by the user option turboConcurrent: a value < 1 (including unset) means no Turbo permission,
and creation returns TURBO_CONCURRENCY_LIMIT immediately; the same code is returned when all slots are occupied.

Lifecycle

A client must connect to the WS within 60 seconds after creation succeeds (cancelAfter in the response), otherwise the channel is reclaimed

After the last client disconnects there is likewise a 60-second grace period, after which the upstream and the concurrency slot are released

The Redis channel record has a 24-hour TTL, used only as crash-recovery cleanup, and does not represent how long the channel stays usable

A client whose backlog exceeds 16MB unconsumed is disconnected with close code 1013 (slow-consumer protection)

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 ********************

WebSocket protocol

Connection

client → server

server → client

WS error body differs from HTTP

Limits

Lifecycle

Request

Request Code Samples

Responses

Close a Turbo channel

WebSocket protocol#

Connection#

client → server#

server → client#

WS error body differs from HTTP#

Limits#

Lifecycle#

Request

Request Code Samples

Responses

WebSocket protocol

Connection

client → server

server → client

WS error body differs from HTTP

Limits

Lifecycle