Live dictation stream

A dictation client opens a session with an API key, receives a signed ticket, and opens one WebSocket. Speech to text and corrections run over the socket without a job per request. Citadel relays every frame to the speech runtime unchanged and records counts and timings per request. Citadel stores no audio, no transcript and no chat content. Base URL: https://citadel.albastov.com/v1/dictation.

Note. The stream is experimental and off unless the owner switches it on. Scope dictation is owner-only: a member's key cannot carry it. The examples need a key with scope dictation; the example checker skips them.

Flow

1. POST /v1/dictation/sessions with an API key. The response contains session_id, ticket and endpoints.
2. Open the relay endpoint URL. Send {"op":"auth","ticket":"<ticket>"} as the first frame within 5 seconds.
3. Send requests and audio. Read replies in any order; each reply carries the request id.
4. After a disconnect, call POST /v1/dictation/sessions/{id}/ticket and open the socket again with the new ticket. Resend unanswered requests.

POST /v1/dictation/sessions

Requires an API key with scope dictation. The body is optional.

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

Returns 201:

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

expires_at is the ticket expiry in Unix milliseconds. Try endpoints in order; a later version adds endpoints of other kinds to the same list.

POST /v1/dictation/sessions/{id}/ticket

Requires an API key with scope dictation of the account that opened the session. Returns 200 with the same body as session creation and a new ticket for the same session. A session of another account fails with 404 session_not_found.

Session ticket

The ticket is a compact JWS signed with Ed25519: base64url(header).base64url(claims).base64url(signature).

A ticket opens one socket at a time and only before exp. An open socket outlives the ticket. A second socket with a ticket that holds an open socket fails with ticket_in_use. A socket opened with a new ticket of the same session closes the older socket of the session with 4409 replaced. A ticket issued before the ticket of the open socket fails with ticket_stale.

Citadel checks the API key that opened the session when a socket opens and every 30 seconds while the socket is open. A revoked key, or a key without scope dictation, closes the socket with 4401 invalid_key or 4403 scope_missing.

GET /v1/dictation/keys

Requires no key. Returns the ticket signing keys:

{
  "alg": "EdDSA",
  "kid": "Xq2mVb7NcL0pRt4s",
  "ticket_key": "2l5yWl0B6bO0cG1o3d7m0Ff3eU6k8n1qYw2s4v9x0zA=",
  "keys": [
    {"kid": "Xq2mVb7NcL0pRt4s", "alg": "EdDSA", "public_key": "2l5yWl0B6bO0cG1o3d7m0Ff3eU6k8n1qYw2s4v9x0zA=",
     "active": true, "created_at": 1793567100000, "retired_at": null}
  ]
}

ticket_key is the active key: the raw 32-byte Ed25519 public key, base64. After a key rotation, keys also lists the previous key for 5 minutes, the lifetime of the tickets the previous key signed. Responses include Cache-Control: public, max-age=60. One client address may call the route 60 times a minute.

GET /v1/dictation/stream

WebSocket upgrade. Query parameter: session=<session_id>. Never put the ticket in the URL.

Authenticate in one of two ways:

After authentication, every frame passes unchanged in both directions, in order per direction. Citadel sends no frame of its own. A refusal by the speech runtime arrives as a close frame (4000 + status) or, with the header method, as the runtime's HTTP status and body.

import json, os, requests
from websockets.sync.client import connect

base = "https://citadel.albastov.com/v1"
session = requests.post(f"{base}/dictation/sessions",
                        headers={"Authorization": f"Bearer {os.environ['CITADEL_API_KEY']}"},
                        json={"client": "example"}).json()
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
    print(json.loads(ws.recv()))

Limits

Send a frame at least every 90 seconds, or answer pings: the network edge closes a WebSocket after 100 seconds without traffic. {"op":"ping"} is an end-to-end check and receives {"op":"pong"} from the runtime. The runtime accepts audio up to 120 seconds, but a frame over 1 MiB never reaches the runtime: send a final at each pause.

Protocol

Client text frames are one JSON object each; 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 contains received (Unix milliseconds when the runtime read the request) 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; the replaced request receives error with code replaced.

Request errors

{"op":"error","id":n,"code":"...","message":"...","ms":{...}}. The socket stays open.

Errors

HTTP errors use the Citadel error body: {"ok": false, "error": "dictation-off", "code": "dictation_off", "message": "..."}.

Close codes

Other codes from the runtime pass to the client unchanged.

Records

Citadel records sessions, sockets (frame and byte counts) and one row per request from the runtime's summary events: operation, outcome, model, audio length, character and token counts, and the ms timings. Records are kept 90 days. Citadel writes records in batches after the reply; while the database is unreachable, the records of that period are lost and the stream continues.