Streaming transcription
GET /v1/stt/stream — live transcription over WebSocket.
Connecting
Open a WebSocket to wss://router.speko.dev/v1/stt/stream with both required headers on the upgrade:
Authorization: Bearer sk_speko_...
Idempotency-Key: <unique key>Browsers cannot set these headers on a WebSocket upgrade — connect from your backend.
Session lifecycle
The first frame you send must be session.configure, within 10 seconds of connecting. Its exact bytes are the idempotency content hash for the session.
{
"type": "session.configure",
"routing": { "mode": "auto", "objective": "latency" },
"audio": { "encoding": "pcm_s16le", "sample_rate_hz": 16000, "channels": 1 },
"language": "en"
}audio.encodingstringrequiredpcm_s16le or opus.
audio.sample_rate_hznumberrequired8000–192000.
audio.channelsnumberrequired1–8.
Then:
- Send audio as binary frames in the configured format.
- Send
{"type":"input.commit"}to ask for final results for the audio so far, for example at the end of a turn. See commits. - Send
{"type":"session.close"}to end the session.
Server frames
The first server frame is always session.ready:
{ "type": "session.ready", "request_id": "rreq_...", "route": { "provider": "cartesia", "model": "ink-2", "region": "eu-west-1", "attempt_id": "ratt_..." } }| Frame | Meaning |
|---|---|
session.ready | Session admitted and routed; always first |
transcript.delta | Interim hypothesis: {"type":"transcript.delta","text":"..."} (text is always non-empty) |
transcript.final | Finalized text: {"type":"transcript.final","text":"...","segments":[...]} |
usage.updated | Running usage snapshot |
session.closed | Clean end: {"type":"session.closed","usage":{...}} |
error | Terminal failure — the standard error envelope |
Exactly one terminal frame ends every session: session.closed or error. A socket that drops without either was truncated — treat results as incomplete.
Commits
Every input.commit gets exactly one transcript.final in reply, in the order you sent the commits. The final is empty ("text":"") when nothing was left to finalize or the provider did not answer in time. The session stays open after a commit.
The provider can also send finals on its own, for example when it detects the end of an utterance. To tell the reply to your commit from those, give the commit an id:
{ "type": "input.commit", "commit_id": "turn-7" }session.ready carries "commit_ids": true when the Router echoes commit ids, so you can choose this mode from the first frame. The final that answers a commit carries the same id:
{ "type": "transcript.final", "text": "book a table for two", "commit_id": "turn-7" }commit_idstringOptional. 1–64 characters of A-Z a-z 0-9 . _ : -. Any other value ends the session with invalid_request.
- A final without
commit_ideither came from the provider on its own or answers a commit you sent without an id. - When one provider final covers several of your commits, each older commit gets an empty final with its own id first, and the text arrives with the newest commit's id.
- On
session.close, commits that are still unanswered get their finals beforesession.closed.
Liveness and limits
- The Router pings every 20 seconds; frames are capped at 1 MiB.
- Streaming sessions meter audio duration against a lease that the Router renews internally. If the session's budget or lease cannot be extended, the stream terminates with
budget_exhaustedorlease_expired— these two codes only ever appear on established streams, never as HTTP statuses.