Skip to navigation
Speech to TextRealtime

Realtime transcription

View as Markdown

Stream 16 kHz PCM16 mono audio as base64 JSON events over an authenticated WebSocket.

Event flow

  1. Send session.configure immediately after connecting, then wait for session.configured.
  2. Send input_audio_buffer.append events while receiving optional transcript.partial results.
  3. Send input_audio_buffer.commit. Receive input_audio_buffer.committed, then transcript.completed for that utterance.

VAD and automatic duration boundaries can also commit an utterance. An empty manual commit returns input_audio_buffer.commit_empty. The connection stays open for subsequent utterances. The audio example contains one 20 ms PCM16 chunk. Append all chunks before committing an utterance. Transcript examples illustrate the event format.

Handshake

WSS
wss://api.narilabs.com/v1/realtime?intent=transcription

Authentication

AuthorizationBearer
Nari API key in the WebSocket handshake Authorization header.

Send

session.configureobjectRequired
Send once within 10 seconds of connecting. Wait for `session.configured` before sending audio. Open a new connection to change settings.
OR
input_audio_buffer.appendobjectRequired
Send audio in a JSON text frame and receive results concurrently. Appends have no individual acknowledgement.
OR
input_audio_buffer.commitobjectRequired
Commit pending audio. The server returns `input_audio_buffer.committed`, followed by `transcript.completed`. With no pending audio, it returns `input_audio_buffer.commit_empty` instead.

Receive

session.configuredobjectRequired
Configuration accepted; audio can now be sent. Returns applied settings and `session.limits`.
OR
transcript.partialobjectRequired
Replace the previous partial for this `item_id`; earlier words can change. A completed result can arrive without any partial.
OR
transcript.completedobjectRequired
Final result for this utterance. Replaces any partial text and leaves the connection open.
OR
transcript.wordsobjectRequired
Word-level alignment for an opted-in completed transcript. Match it by `item_id`; alignment is asynchronous, so other utterance events can arrive first.
OR
transcript.words.failedobjectRequired
Terminal alignment failure for an opted-in completed transcript. The matching `transcript.completed` remains valid.
OR
input_audio_buffer.committedobjectRequired
Acknowledges a manual, VAD, or duration boundary. Use `item_id` to match the subsequent `transcript.completed` result.
OR
input_audio_buffer.speech_startedobjectRequired
Sent when server VAD detects the start of speech.
OR
input_audio_buffer.speech_stoppedobjectRequired
Sent when server VAD detects enough silence to end speech.
OR
errorobjectRequired
Reports an error before the connection closes. Use `error.code` to choose the next action. For `INSUFFICIENT_CREDITS`, stop sending audio and add credits before reconnecting. See [Errors and troubleshooting](/errors#websocket-failures).
OR
input_audio_buffer.commit_emptyobjectRequired
No audio is pending, so this commit produces no new final result. Previously committed utterances may still have results pending.