Varmirdocs
Docs/API reference/WS /api/v1/stream
WS

/api/v1/stream

Bidirectional WebSocket for live transcription with partial results as you speak.Authentication required

Send live 16 kHz mono PCM and get draft text while the person speaks, a finished segment after each pause, and an optional translation of every segment. From a server, put your API key in the first message. From a browser, use a 60-second stream token from POST /api/v1/stream/token instead (see Browser microphone capture) — never put the API key in browser code.

Connect

Open a WebSocket to wss://api.varmir.com/api/v1/stream and, within 10 seconds, send a config message with your API key or a stream token (vst_…) as token (or send the API key in an Authorization: Bearer header). sample_rate must be 16000; language and translate_to are optional.

JavaScript
const ws = new WebSocket("wss://api.varmir.com/api/v1/stream");

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "config",
    token: "mstk_your_key",
    sample_rate: 16000,
    language: "uk",
    translate_to: "en",
  }));
};

Message protocol

After config_ok, send raw PCM as binary messages, 20-200 ms per frame (at most 4 seconds per frame). To finish, send {"type": "end"}: the server transcribes what is left, sends the remaining final and translation events, then done, and closes the socket. Closing the socket yourself also ends the stream and you are charged for the audio sent.

overview
// First message: config
{
  type: "config",
  token: "mstk_...",
  sample_rate: 16000,
  audio_format: "pcm_s16le", // or "pcm_f32le"
  language: "uk", // optional, auto-detected if omitted
  translate_to: "en" // optional
}

// Then: raw 16 kHz mono PCM (binary), 20-200 ms per frame
ws.send(audioChunk);

// To stop: send end, then read until "done"
ws.send(JSON.stringify({ type: "end" }));

Server events

EventDirectionDescription
config_okserver → clientThe config was accepted and the first 5-second billing block charged. Fields: id, sample_rate, audio_format, language, translate_to, billing_block_sec. Start sending audio.
partialserver → clientDraft text of the segment being spoken right now (text). Replace the previous partial; it resets after each final.
finalserver → clientA finished segment: segment (0, 1, 2…), text, language, start and end in seconds from the stream start. Append it to your transcript. Segments end at natural pauses, at most ~15 s long.
translationserver → clientTranslation of a final segment (segment, language, text). Sent only with translate_to, right after the matching final.
errorserver → clientcode and message, same codes as REST: invalid_request, invalid_api_key, insufficient_credits, rate_limited, service_unavailable. Except invalid_request on a stray text message, the stream then ends with done.
doneserver → clientLast message before the server closes the socket: id, duration_sec, charged_sec, segments, and reason if the stream was stopped by the server (insufficient_credits, idle_timeout, max_duration).

Billing and limits

Streams are billed per second of audio sent, from your plan quota first and then from credits, like /transcribe. Seconds are reserved in 5-second blocks ahead of the audio; when the stream ends, the unused part of the last block is returned, so you pay for the audio length rounded up to a whole second. A stream with no audio is not charged. If the next block cannot be paid, you get insufficient_credits, audio beyond the paid seconds is dropped, and the stream ends with done after the paid audio is transcribed. One stream counts as one request in your usage.

Up to 5 concurrent streams per key; a stream with no audio for 30 seconds is closed; a single stream lasts at most 4 hours.

Code examples

A client that pipes PCM into the stream and renders partial and final segments. Run it on your server and relay audio from your app; the key must not reach the browser.

stream.js
const ws = new WebSocket("wss://api.varmir.com/api/v1/stream");

ws.onopen = () => ws.send(JSON.stringify({
  type: "config",
  token: "mstk_your_key",
  sample_rate: 16000,
  translate_to: "en",
}));

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "partial") updatePartial(msg.text);
  if (msg.type === "final") commitFinal(msg.text);
  if (msg.type === "translation") commitTranslation(msg.text);
};

// Pipe 16 kHz mono s16le PCM frames (e.g. relayed from your app)
micFrames.on("data", (chunk) => ws.send(chunk));