Fetch a synthesized audio stream

Fetch an MP3 audio stream by audio ID. The URL is given directly in the response of POST /api/tts/simple-generate (stream mode) and similar endpoints,
and usually does not need to be assembled by the caller.

Independent auth (Bearer JWT is not used)

This endpoint is JWT-exempt (app.js:262 already excludes /api/tts/stream/* from the auth middleware),
and instead uses query parameter auth carrying a 32-character static token:

Tokens are issued per user, stored in Redis auth:user:{token}, TTL 7 days; the same user reuses the same token while it is valid

The token itself only resolves to a userId; the audio's ownership is then checked, mismatch returns AUTH_FORBIDDEN

An invalid or expired token returns AUTH_UNAUTHORIZED

Because the credential is in the URL, these addresses can be handed directly to an <audio> tag, a player, or a download tool,
but they should not be written to public logs or used as long-lived share links.

Streaming and range requests

The same id is fetched from upstream only once on the server; multiple requests (including iOS Range continuation) share one cached session

Range requests are supported (206 Partial Content); an out-of-range offset returns 416; HEAD probes return headers immediately without blocking

An ETag is sent, used with If-Range to prevent concatenating corrupted audio across sessions

When the audio fails before producing any bytes, a standard JSON error body is returned rather than an empty stream:
upstream fetch failure is STREAM_FETCH_FAILED, session exceeding max lifetime is STREAM_TIMEOUT,
instruct_mode synthesis itself failing is TTS_GENERATE_FAILED

Stream metadata TTL is 7 days; after expiry, STREAM_NOT_FOUND is returned

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

Fetch a synthesized audio stream

Independent auth (Bearer JWT is not used)

Streaming and range requests

Request

Request Code Samples

Responses

Fetch a synthesized audio stream

Independent auth (Bearer JWT is not used)#

Streaming and range requests#

Request

Request Code Samples

Responses

Independent auth (Bearer JWT is not used)

Streaming and range requests