---
title: "Synthesize one utterance to a raw audio stream"
method: POST
path: "/v1/tts/speech"
---

# Synthesize one utterance to a raw audio stream

`POST /v1/tts/speech`

One-shot text-to-speech. The response body is a raw audio stream in the requested output format; the route and the billed character count come back in headers (Speko-Provider, Speko-Model, Speko-Region, Speko-Usage-Characters) because a byte stream has no place for a JSON envelope.

## Headers

- `Idempotency-Key` string, required

## Request body

- SpeechRequest — The POST /v1/tts/speech body. The response is a raw audio stream; the route and billed character count come back in headers because a byte stream has no place for a JSON envelope.
  - `routing` Routing — Selects how the Router picks a provider for one request. It is a tagged union over mode: auto carries the objective and optional allow/deny provider filters, explicit carries exactly a provider and model. Fields from the other arm are rejected in both directions; a present-but-empty filter array ([]) counts as present and is rejected in explicit mode, while an empty-string provider or model in auto mode is indistinguishable from omission and tolerated as such. A wholly omitted routing object means {mode: auto, objective: balanced}, and an auto routing without an objective defaults to balanced — the default exists for omission, never for partially specified routing. Explicit mode also accepts the combined "provider/model" spelling in the model field: {"model": "openai/gpt-5.2"} with no provider splits at the first slash, and a model redundantly prefixed with the stated provider has the prefix stripped. Upstream model ids that themselves contain a slash must therefore name the provider one way or the other, e.g. "together/meta-llama/Llama-X" or provider "together" with model "meta-llama/Llama-X".
    - `mode` 'auto' | 'explicit' — Discriminates the routing tagged union. The set is closed: an empty or unknown mode is rejected so a typo can never silently fall back to automatic provider selection.
    - `objective` 'balanced' | 'quality' | 'latency' | 'cost' — Ranks auto-mode candidates. Unknown objectives are rejected rather than treated as balanced so callers learn about typos before any money is reserved.
    - `allow_providers` string[] — Auto mode only. Provider ids must not be blank.
    - `deny_providers` string[] — Auto mode only. Provider ids must not be blank.
    - `provider` string — Explicit mode only, and required there.
    - `model` string — Explicit mode only, and required there. Accepts either the bare model id with the provider field set, or the combined "provider/model" form with the provider field omitted.
  - `input` string, required — The text to synthesize.
  - `voice` string — Optional: in auto mode the party that picks the provider picks a default voice for it.
  - `language` string — Optional language hint. Auto routing ranks candidates on that language's benchmark board and the Router picks a voice curated for it; omitted means English.
  - `audio` AudioConfig, required — Raw audio on a Router stream: the output format of a TTS request, or the binary input frames of an STT stream. The bounds match the local gateway's portable media contract so a caller can move between provider-direct and Router routes without re-encoding.
    - `encoding` 'pcm_s16le' | 'opus', required
    - `sample_rate_hz` integer, required
    - `channels` integer, required

## Response `200`

The synthesized audio, in the encoding, sample rate, and channel count the request asked for.

## Other responses

- `429` — The request exceeded an edge request quota, an organization concurrency limit, or a provider rate limit. The body identifies the stable failure class; Retry-After gives the minimum safe delay.
- `default` — Normalized failure. Every non-2xx response carries this envelope; the Router never forwards a raw provider response body.

## Changes

- **2026-08-24** `9774b21e73da` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/speko/apis/speko-voice-router-api/changes/v1/tts/speech/post.md)

---

[API](https://skmtc.dev/speko/apis/speko-voice-router-api.md) · [All operations](https://skmtc.dev/speko/apis/speko-voice-router-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/speko/speko-voice-router-api/revisions/890238de6e30/schema)