One-shot synthesis returning an MP3 stream directly

One-shot text-to-speech that returns audio bytes directly as an audio/mpeg stream, usable as <audio src> as-is.

Relationship to `GET /api/tts/simple-generate`

Both share the same parameters, auth, billing, and response headers,
and both emit a byte stream with direct_stream: true. The .mp3 suffix exists purely so browsers, players, and download tools
recognize the content type by extension; there is no difference in response shape.

For a JSON response (to obtain streamUrl and fetch later) use POST /api/tts/simple-generate without direct_stream.

Preconditions

Paying users only, otherwise TTS_PAID_ONLY

By default API Key calls only: a session JWT returns TTS_SESSION_TOKEN_NOT_ALLOWED

DANGER

Over-limit requests do not fail immediately; they may wait about 330 seconds before RATE_LIMIT_CONCURRENT. Set the client HTTP timeout above 330 seconds. See the "Text to speech" document.

Two synthesis modes

TTS: pass text. When instruct_mode=true the emotion-controllable path is used,
supporting {{...}} control markers (billing and duration estimates are computed after stripping markers), and no SRT is produced

VC (voice conversion): pass input_audio. text and all TTS parameters are then ignored,
billed by input-audio duration; input_audio must be an address under this platform's /vc-input/ or /generate/ path,
or an authorized external address, otherwise TTS_INPUT_AUDIO_INVALID

Error semantics

All errors are decided before response headers are sent, so failures return a standard JSON error body (not an audio stream).
Once bytes start flowing, a mid-stream failure can only appear as an early end of the stream.

Synthesis failure is not billed; billing happens after audio is produced successfully.

INFO

See the Errors document for the full code reference. Always use the X-Vocu-App-Request-Id response header when troubleshooting.

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

🟢200Success

audio/mpeg

MP3 audio byte stream. The response body is the audio itself. Accompanying metadata (audio ID, reusable stream URL, billing details) is sent as a JSON string in the X-Reecho-Response-Data response header.

Headers

Bodyaudio/mpeg

Example

{}

🟠400Bad request

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠409Conflict

🟠429Rate limited

🔴500Server error

🔴503Temporarily unavailable

One-shot synthesis returning an MP3 stream directly

Relationship to GET /api/tts/simple-generate#

Preconditions#

Two synthesis modes#

Error semantics#

Request

Request Code Samples

Responses

Relationship to `GET /api/tts/simple-generate`

Preconditions

Two synthesis modes

Error semantics