From 335b78b4352fbaaf134bd7f3c9304444df11ed20 Mon Sep 17 00:00:00 2001 From: Richard R Date: Tue, 9 Jun 2026 10:44:16 -0600 Subject: [PATCH] docs(tts): clarify OpenAI-compatible provider requirements and supported formats Update documentation to specify that only the speech endpoint is required for OpenAI-compatible TTS providers, with voice listing now optional and auto-discovered. Document support for multiple audio formats (mp3, wav, ogg, flac) and note that API keys are optional for local or unauthenticated servers. Add Supertonic to the list of compatible implementations and improve troubleshooting guidance. --- .../docs/configure/tts-provider-guides/other.md | 12 +++++++----- docs-site/docs/configure/tts-providers.md | 8 +++++--- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs-site/docs/configure/tts-provider-guides/other.md b/docs-site/docs/configure/tts-provider-guides/other.md index 4e3aafc..1d247a0 100644 --- a/docs-site/docs/configure/tts-provider-guides/other.md +++ b/docs-site/docs/configure/tts-provider-guides/other.md @@ -6,12 +6,14 @@ Use any OpenAI-compatible TTS service with OpenReader, including self-hosted ser ## Requirements -Your service must expose these endpoints: +Your service only needs an OpenAI-compatible speech endpoint: -- `GET /v1/audio/voices` -- `POST /v1/audio/speech` +- `POST /v1/audio/speech` — **required**. +- Voice listing is **optional** and auto-discovered from `/v1/audio/voices`, `/v1/voices`, or `/v1/styles`; OpenReader falls back to default voices if none are available. -Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi). +The endpoint may return `mp3`, `wav`, `ogg`, or `flac` — OpenReader normalizes non-mp3 audio to mp3 automatically. An API key is optional. + +Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi), [Supertonic](./supertonic). ## Setup @@ -44,7 +46,7 @@ See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior. ## Troubleshooting -If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape. +If voices don't load, confirm the server is reachable from the Next.js runtime and that at least one of `/v1/audio/voices`, `/v1/voices`, or `/v1/styles` returns a valid response. If none do, OpenReader falls back to default voices — synthesis still works as long as `POST /v1/audio/speech` succeeds. ## References diff --git a/docs-site/docs/configure/tts-providers.md b/docs-site/docs/configure/tts-providers.md index 376e1dc..b0e0565 100644 --- a/docs-site/docs/configure/tts-providers.md +++ b/docs-site/docs/configure/tts-providers.md @@ -31,10 +31,12 @@ For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. F ## Custom provider requirements -Self-hosted or custom providers must expose OpenAI-compatible audio endpoints: +Self-hosted or custom providers only need an OpenAI-compatible speech endpoint: -- `GET /v1/audio/voices` -- `POST /v1/audio/speech` +- `POST /v1/audio/speech` — **required**. +- Voice listing is **optional** and auto-discovered: OpenReader probes `/v1/audio/voices`, `/v1/voices`, then `/v1/styles`, and falls back to sensible default voices if none respond. + +The speech endpoint may return any common audio format — `mp3`, `wav`, `ogg`, or `flac`. OpenReader detects the format and transcodes non-mp3 audio to mp3 automatically, so your server does not need to honor `response_format: mp3`. An API key is optional; keyless servers work. :::warning TTS requests are server-side TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.