Speko Docs
Speech to text

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.encodingstringrequired

pcm_s16le or opus.

audio.sample_rate_hznumberrequired

8000–192000.

audio.channelsnumberrequired

1–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_..." } }
FrameMeaning
session.readySession admitted and routed; always first
transcript.deltaInterim hypothesis: {"type":"transcript.delta","text":"..."} (text is always non-empty)
transcript.finalFinalized text: {"type":"transcript.final","text":"...","segments":[...]}
usage.updatedRunning usage snapshot
session.closedClean end: {"type":"session.closed","usage":{...}}
errorTerminal 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_idstring

Optional. 1–64 characters of A-Z a-z 0-9 . _ : -. Any other value ends the session with invalid_request.

  • A final without commit_id either 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 before session.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_exhausted or lease_expired — these two codes only ever appear on established streams, never as HTTP statuses.

On this page