Stream the full generated audio

Stream the audio of the entire generation task as it is produced (all content concatenated in index order into one continuous MP3).

Differences among the three related endpoints

Endpoint	Returns	Granularity
`GET /api/tts/generate/{id}/stream.mp3`	MP3 byte stream	Entire generation task
`GET /api/tts/generate/{id}/{contentIndex}/stream.mp3`	MP3 byte stream	Single content
`GET /api/tts/generate/{id}/stream`	JSON containing the full URL of the first endpoint above	Entire generation task (URL lookup only)
`GET /api/tts/generate/{id}/{contentIndex}/pseudo/stream.mp3`	302 redirect to the finished audio	Single content (pseudo-streaming)

Response branches

The generation task's metadata.audio already exists (finished audio has landed in storage) → 302 redirect to the finished audio URL; the streaming pipeline is not used.

Task status is processing or generated → return an MP3 byte stream.

Any other status → JSON error STREAM_NOT_READY.

Byte stability and Range

The same {id} + {i} share one stream session: the generation pipeline runs globally once, output is appended into the session cache, and every HTTP request reads from the cache.
Therefore this URL is a byte-stable, resumable resource with full support for Range / If-Range / HEAD / 206 / 416 (iOS AVPlayer depends on this semantics).
The session is reclaimed after 30 minutes of idle (sliding window); a later visit rebuilds and re-fetches upstream, transparent to the client, but the ETag changes.

When error responses can appear

Only when not a single byte has been sent yet is a failure translated into a JSON error response; once audio has started flowing, a mid-stream failure only truncates the stream and will not produce a JSON error body.

Audio output parameters (no tunable parameters)

Output container / encoding is fixed as MP3 (Content-Type: audio/mpeg); the endpoint does not accept format / bitrate / sampleRate parameters.

Regular concat path: every segment is fed into the same libmp3lame pipeline and re-encoded at a fixed bitrate of 320 kbps (routes/generate/streaming.js:220-221). That pipeline does not explicitly set a sample rate; sample rate is inherited from the upstream segments.

Passthrough path: a single-content instruct/design progressive stream skips ffmpeg entirely, bytes are forwarded as-is (routes/generate/streaming.js:861-869). That path requests 24 kHz MP3 from upstream (routes/generate/streaming.js:842), so this path's output is neither 320 kbps nor 44.1 kHz.

interval silence-fill segments are encoded separately from 44.1 kHz / stereo PCM into 320 kbps MP3 (routes/generate/streaming.js:391-394,421).

Does not return X-Reecho-Audio-Id / X-Reecho-Response-Data

These two response headers exist only on the direct_stream: true direct-return branch of POST /api/tts/generate (routes/generate/tts.js:1789-1798)
and the equivalent branch of simple-generate (routes/generate/tts.js:1321-1322). Those are the only two write sites in the whole repo; they do not exist in routes/generate/streaming.js,
so billing information (credit_used / billing / estimatedDuration) cannot be obtained from this endpoint's response headers — use the generation-task detail endpoint instead.

Auth

This path is on the regex allowlist at app.js:261; both express-jwt and API-key middleware are skipped; only the ?auth= static token is accepted.

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

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200成功

audio/mpeg

返回 MP3 音频流。生成进行中为 200 + Transfer-Encoding: chunked；生成已完成为 200 + Content-Length；带合法 Range 时为 206 + Content-Range；Range 起始越界且会话已完成时为 416；成品音频已存在时为 302 跳转。HEAD 请求只回头部、不跟随流。

Headers

Bodyaudio/mpeg

Example

{}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠404记录不存在

🟠429