Live dictation

Live dictation runs speech to text and chat corrections over one WebSocket per session, without a job per request. The stream is experimental and off unless the owner switches it on (503 dictation_off). Only keys of the albastov.com owner account carry the dictation scope. The API stores no audio, no transcript and no chat content.

Flow

1. POST /v1/dictation/sessions with an API key. The response holds session_id, ticket and endpoints.
2. Open the url of the relay endpoint as a WebSocket. Send {"op":"auth","ticket":"<ticket>"} as the first frame within 5 seconds.
3. Send requests and audio. Replies arrive in any order; each reply carries the request's id.
4. After a disconnect, call POST /v1/dictation/sessions/{id}/ticket and open the socket again with the new ticket. Resend the requests that had no final reply.

Session

A session belongs to the account of the key that opened the session. client names the app and its version, at most 64 printable characters.

curl https://api.albastov.com/v1/dictation/sessions \
  -H "Authorization: Bearer $ALBASTOV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client": "iridium-live 2.4"}'

{
  "session_id": "ds_k3m2c7x4q5n6p2r7s3t4u5v6",
  "ticket": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiLi4uIn0.c2lnbmF0dXJl",
  "expires_at": 1793567400000,
  "endpoints": [
    {"kind": "relay", "url": "wss://api.albastov.com/v1/dictation/stream?session=ds_k3m2c7x4q5n6p2r7s3t4u5v6"}
  ]
}

expires_at is the ticket's expiry in Unix milliseconds. Open each endpoint's url exactly as returned, in list order; a later version adds endpoints of other kinds to the same list.

Ticket

The ticket is a compact JWS signed with Ed25519: base64url(header).base64url(claims).base64url(signature). GET /v1/dictation/keys returns the public keys that verify tickets.

• A ticket opens one socket at a time, and only before exp. An open socket outlives its ticket.
• A second socket with a ticket that holds an open socket fails with ticket_in_use.
• A socket opened with a newer ticket of the same session closes the older socket with 4409 replaced.
• A ticket older than the ticket of the open socket fails with ticket_stale.
• The API checks the key that opened the session when a socket opens and every 30 seconds after. A revoked key, or a key without the dictation scope, closes the socket with 4401 invalid_key or 4403 scope_missing.

Stream

GET /v1/dictation/stream?session=<session_id> upgrades to a WebSocket. Never put the ticket in the URL.

After authentication, every frame passes unchanged in both directions, in order per direction. The API adds no frame of its own.

import json
import os
import urllib.request

from websockets.sync.client import connect  # pip install websockets

req = urllib.request.Request(
    "https://api.albastov.com/v1/dictation/sessions",
    data=json.dumps({"client": "example"}).encode(),
    headers={"User-Agent": "my-app/1.0", "Authorization": f"Bearer {os.environ['ALBASTOV_API_KEY']}", "Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=30) as res:
    session = json.load(res)

with connect(session["endpoints"][0]["url"]) as ws:
    ws.send(json.dumps({"op": "auth", "ticket": session["ticket"]}))
    ws.send(json.dumps({"op": "transcribe", "id": 1, "final": True}))
    ws.send(open("phrase.pcm", "rb").read())  # 16 kHz mono PCM16 little-endian, 1 MiB at most
    print(json.loads(ws.recv()))

Messages

A client text frame is one JSON object; audio is a binary frame. id is a whole number or a string of 1 to 64 characters, unique among the requests in flight. Every request receives exactly one final reply: text, done or error.

ms holds received (Unix milliseconds when the request was read) and total (milliseconds from received to the reply), plus queued and inference for transcribe, and queued and ttft for chat.

Final phrases run before captions. A new caption request ("final": false) replaces the session's pending caption, and the replaced request receives error with code replaced. Send a final at each pause in speech.

Error replies

{"op":"error","id":n,"code":"...","message":"...","ms":{...}} ends one request; the socket stays open.

Limits

An idle WebSocket closes after 100 seconds without traffic: send a frame at least every 90 seconds, or answer pings. {"op":"ping"} is an end-to-end check and receives {"op":"pong"}.

Close codes

Every refusal code: Dictation reference.

Records

Sessions, sockets (frame and byte counts) and one row per request (operation, outcome, model, audio length, character and token counts, and the ms timings) are kept for 90 days. Audio, transcripts and chat content are never stored.

Reference

• Dictation reference: every route, parameter and error.