Realtime

Real-time speech-to-text transcription over WebSocket.

wss://api.reson8.dev/v1/speech-to-text/realtime

Request

Headers

Header	Value
Authorization	`ApiKey <api_key>` or `Bearer <access_token>`
Sec-WebSocket-Protocol	`bearer, <access_token>`

See Authentication for which header to use in different situations.

Query Parameters

Parameter	Type	Default	Description
`encoding`	string	`auto`	Audio encoding: `auto` or `pcm_s16le`
`sample_rate`	number	`16000`	Sample rate in Hz (only used depending on encoding)
`channels`	number	`1`	Number of audio channels (only used depending on encoding)
`custom_model_id`	string		Optional. ID of a custom model to bias transcription. Overrides the model configured on the API client
`include_timestamps`	boolean	`false`	Include `start_ms` and `duration_ms` on transcripts and words
`include_words`	boolean	`false`	Include word-level detail on transcripts
`include_confidence`	boolean	`false`	Include `confidence` on words
`include_interim`	boolean	`false`	Include interim (partial) results and the `is_final` flag

Example

PythonJavaScript (Browser)

import asyncio
import websockets

async def transcribe():
    url = "wss://api.reson8.dev/v1/speech-to-text/realtime"
    headers = {"Authorization": "ApiKey <your_api_key>"}

    async with websockets.connect(url, additional_headers=headers) as ws:
        # Send audio data and control messages...

        async for message in ws:
            print(message)

asyncio.run(transcribe())

const token = "<your_access_token>";
const url = "wss://api.reson8.dev/v1/speech-to-text/realtime";

// Passes token via Sec-WebSocket-Protocol header
const ws = new WebSocket(url, ["bearer", token]);

ws.onopen = () => {
  // Send audio data and control messages...
};

ws.onmessage = (event) => {
  console.log(event.data);
};

Sending Messages

Audio

Binary WebSocket frame containing audio data.

Flush Request

Force the server to finalize any buffered audio and return a transcript.

{
  "type": "flush_request",
  "id": "abc123"
}

Field	Type	Required	Description
`id`	string	No	Optional identifier, returned in the flush corresponding response

Receiving Messages

Transcript

Returned when speech is recognized. By default, only final results are returned. When include_interim=true, interim (partial) results are also returned — these may change as more audio is processed.

DefaultEverything Included

{
  "type": "transcript",
  "text": "the patient presented with chest pain"
}

{
  "type": "transcript",
  "text": "the patient presented with chest pain",
  "is_final": true,
  "start_ms": 1200,
  "duration_ms": 2400,
  "words": [
    { "text": "the", "start_ms": 1200, "duration_ms": 200, "confidence": 0.99 },
    { "text": "patient", "start_ms": 1410, "duration_ms": 450, "confidence": 0.98 },
    { "text": "presented", "start_ms": 1880, "duration_ms": 500, "confidence": 0.97 },
    { "text": "with", "start_ms": 2400, "duration_ms": 200, "confidence": 0.99 },
    { "text": "chest", "start_ms": 2620, "duration_ms": 350, "confidence": 0.96 },
    { "text": "pain", "start_ms": 3000, "duration_ms": 600, "confidence": 0.97 }
  ]
}

Field	Type	Included	Description
`text`	string	Always	The recognized text
`is_final`	boolean	When `include_interim=true`	`true` for final, `false` for interim
`start_ms`	number	When `include_timestamps=true`	Start time in milliseconds
`duration_ms`	number	When `include_timestamps=true`	Duration in milliseconds
`words`	array	When `include_words=true`	Word-level detail

Each word contains:

Field	Type	Included	Description
`text`	string	Always	The recognized word
`start_ms`	number	When `include_timestamps=true`	Start time in milliseconds
`duration_ms`	number	When `include_timestamps=true`	Duration in milliseconds
`confidence`	number	When `include_confidence=true`	Confidence score (0 to 1)

Flush Confirmation

Sent after a flush request has been processed. Includes the id if one was provided in the request.

{
  "type": "flush_confirmation",
  "id": "abc123"
}

Field	Type	Included	Description
`id`	string	Always	The identifier from the corresponding flush request, or `null` if none was provided

Errors

Status	Code	Description
400	`INVALID_REQUEST`	Missing or invalid parameters
401	`UNAUTHORIZED`	Invalid or expired credentials
500	`INTERNAL_ERROR`	Unexpected server error