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 bind to the same handler (directSimpleHandler); parameters, auth, billing, and response headers are identical,
and both force direct_stream: true to emit a byte stream. 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,
unless the user has option allowSessionTokenCallApi enabled, or the role is admin

Concurrency is gated by a QPS limiter (regular paying 2 + paidConcurrent, enterprise 5 + paidConcurrent).
Over-limit requests queue rather than failing immediately, waiting up to about 5 minutes 30 seconds before returning RATE_LIMIT_CONCURRENT

Two synthesis modes

TTS: pass text. When instruct_mode=true the VoiceDesign 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 a configured allowlisted 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.

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 音频字节流。响应体即音频本身，附带的元信息（音频 ID、可复用的流地址、计费明细）在响应头 X-Reecho-Response-Data 中以 JSON 字符串下发

Headers

Bodyaudio/mpeg

Example

{}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠404记录不存在

🟠409

🟠429

🔴500服务器错误

🔴503服务器故障

One-shot synthesis returning an MP3 stream directly

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

Preconditions#

Two synthesis modes#