TurnsMarkdown

Turn-level speech-to-text over WebSocket. The server emits events at turn boundaries.

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

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`, `pcm_s16le`, `mulaw`, or `alaw`
`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)
`language`	string		Language to transcribe. Recommended for best quality. When omitted, the server auto-detects each utterance independently. See Languages for supported codes
`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 `turn_end_candidate` and words
`include_words`	boolean	`false`	Include word-level detail on `turn_end_candidate`
`include_language`	boolean	`false`	Include detected `language` on `turn_end_candidate`
`patterns`	string		Optional. Comma-separated regex-style patterns for short alphanumeric tokens (order codes, licence plates) to recover. Only set when the token is likely present — see Patterns

Example

PythonJavaScript (Browser)

import asyncio
import websockets

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

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

        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/turns";

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

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

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

Sending Messages

Audio

Binary WebSocket frame containing audio data.

Receiving Messages

Turn Start

Sent when the speaker begins a new turn. Not emitted when a turn resumes after a Turn Continuation.

{
  "type": "turn_start"
}

Turn End Candidate

Sent when the server detects a silence likely to end the turn. It will either be confirmed by a Turn End or cancelled by a Turn Continuation.

DefaultEverything Included

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

{
  "type": "turn_end_candidate",
  "text": "the patient presented with chest pain",
  "language": "en",
  "start_ms": 1200,
  "duration_ms": 2400,
  "words": [
    { "text": "the", "start_ms": 1200, "duration_ms": 200 },
    { "text": "patient", "start_ms": 1410, "duration_ms": 450 },
    { "text": "presented", "start_ms": 1880, "duration_ms": 500 },
    { "text": "with", "start_ms": 2400, "duration_ms": 200 },
    { "text": "chest", "start_ms": 2620, "duration_ms": 350 },
    { "text": "pain", "start_ms": 3000, "duration_ms": 600 }
  ]
}

Field	Type	Included	Description
`text`	string	Always	The recognized text
`language`	string	When `include_language=true`	The detected language code
`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

Turn End

Confirms that the previous turn end candidate is the final end for the turn.

{
  "type": "turn_end"
}

Turn Continuation

Cancels the previous turn end candidate as the speaker continued speaking. A later turn_end_candidate will include the full text from before and after the continuation.

{
  "type": "turn_continuation"
}

Errors

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