PyAI reference / Streaming

Hear streaming frames

The streaming speech-to-text WebSocket emits bare JSON text frames (no transcript. prefix, no session.started, no usage frame). Render partials live, then commit on speech_final / final.

connect

wss://api.pyai.com/v1/audio/transcriptions/stream?protocol=pyai-hear-v1&model=pyai-hear&encoding=pcm16&sample_rate=16000&interim_results=true

Server to client frames

`partial`

every eager tick#partial

Live hypothesis (may also carry stable_text / active_text). Overwrite it per utterance_id.

Payload

{text, utterance_id, t_ms}

`partial_stable`

when a prefix locks in#partial_stable

The leading portion the recognizer no longer expects to revise.

Payload

{text, utterance_id, t_ms}

`speech_final`

on endpoint or after commit#speech_final

End of an utterance, stable.

Payload

{text, utterance_id, t_ms, audio_ms}

`final`

follows speech_final#final

Corrected full-context transcript for the utterance.

Payload

{text, utterance_id, t_ms, audio_ms}

`error`

on fault#error

An error frame for a stream-level fault.

Payload

{code, message}

Client to server control frames

Stream binary audio frames (PCM16 little-endian mono at the negotiated sample_rate, or opus) continuously. Use these JSON text frames for control:

`commit`

#frame-commit

{"type":"commit"}

Force-finalize the current utterance (e.g. when your VAD detects end-of-turn). The engine flushes a speech_final / final for the audio buffered so far.

`config`

#frame-config

{"type":"config","grounding":true}

Reserved Cue configuration. It is not active on the serving Hear stream.

`end`

#frame-end

{"type":"end"}

Ignored by the engine - this is NOT a flush. Use commit (or close the socket) to finalize.

Close codes

Code	Meaning
`1000`	Normal close.
`1008`	Auth/policy: bad key, missing hear:stream scope, or revoked engine token.
`1011`	Engine error. A 1011 that arrives immediately after a final is a benign close, not a failed transcription.
`4429`	Over the per-key / fleet concurrency cap.

Migrating from another streaming STT provider? See the Deepgram to PyAI guide for the full frame mapping.

QUESTIONS, ANSWERED

A few useful answers.

What does the Hear streaming reference describe?

It describes the speech-to-text WebSocket messages your application receives and the client messages used to finish an audio stream. Use the documented event names and examples for your integration.

Are interim transcripts final results?

No. Interim text may be revised as more audio arrives. Use the documented result state when deciding which text to keep as a completed transcript.

Where can I find a complete streaming example?

Open the Hear guide and the SDK starters. They provide setup and runnable source alongside this reference for the individual streaming frames.

Stream partials from one socket.

Start free with $50 in free credits - telephony-tuned STT with eager partials and a clean commit flush.

Get API Key