Live transcription API
One WebSocket. You send a consent message, then audio; you receive the transcript, who spoke, and, when asked for, a live analysis. Make keys on your account page.
1. Connect
wss://<host>/v1/listen
Authorization: Bearer pp_...
Where a header cannot be set, use ?token=. A key belongs on a server. For a browser, your server asks for a token that lasts 10 minutes and gives that to the page:
POST https://<host>/v1/sessions
Authorization: Bearer pp_...
{"token": "...", "expires_s": 600} then: wss://<host>/v1/listen?token=...
A wrong or revoked key closes the socket with code 4401.
2. Consent comes first
The first frame must be this JSON text frame. No audio is read before it.
{"type": "consent", "acknowledged": true,
"language": "ar", // REQUIRED: "ar" (Egyptian Arabic) or "en"; no default, refused without it
"live_analysis": false, // true: an analysis at each pause
"mode": "live", // "record": record now, transcribe later
"resume": ""} // a session id, to continue that call
What acknowledged: true means. You state that every person in the recording knows they are being recorded and transcribed and has agreed, and that your product shows them it is recording. Recording people without their knowledge is illegal in many places. Hidden capture is not allowed on this service.
With live_analysis, and when you run an analysis of a finished call, the transcript (text only, never audio) may be sent to OpenAI for processing, without being stored there. Tell your users before you turn it on.
3. Wait for your slot
Every call waits in one queue. With a free slot you get ready at once. Otherwise:
| You receive | Meaning | You may send |
|---|---|---|
queued | position in the line, waiting in total. Sent again when it changes. | {"type":"cancel"} or {"type":"record_later"} |
slot_ready | A slot is held for you for expires_s seconds (15). | {"type":"go"} to start, or the two above |
error with expired | No go in time. The slot went to the next in line; the socket closes (4408). |
record_later leaves the queue and records now: the audio is transcribed when a slot is free (see 7).
4. Ready, then audio
{"type": "ready", "session": "…", "sample_rate": 16000, "frame_ms": 20, "frame_bytes": 640, …}
After ready, send binary frames: 16 kHz, mono, 16-bit signed little-endian PCM, in real time. Any chunk size works. Keep session: it names the call everywhere else.
5. What you send during the call
| Message | Effect |
|---|---|
{"type":"stop"} | Ends the call. The last lines arrive, then stopped. |
{"type":"me","speaker":"…"} | Once per call: this speaker label is your user. From then on the live analysis gives its suggestions to them. |
{"type":"stats"} | Asks for a stats event. |
6. What you receive
| Event | Fields |
|---|---|
speech_started, utterance_ended | at_ms |
transcript | A first, fast line: text, start_ms, end_ms, speaker, and the tone scores arousal, dominance, valence (may be null). |
replaced | The final lines for a stretch of the call. Remove every line whose start_ms is in removed and insert lines (same fields as transcript, with verified: true). span is the stretch in ms. |
speakers | Speaker labels changed for the lines in lines. |
analysis_window | Live analysis only: the lines being analysed, status: "analysing". |
analysis | Live analysis only: summary, so_far (the picture of the whole call so far), observations, flags (each with a suggestion; only after me). |
me | Confirms the speaker you marked. |
stopped | The call is over; carries the call's totals. |
error | detail in plain words. fatal: true means the socket is closing. Flags: credits (balance used up), busy (your account's open-call limit, close code 4429), expired. |
Show transcript lines as they come and treat replaced as the truth. Ignore event types you do not know: new ones may be added.
7. After the call
The same key works on the REST API, on its own data only:
| Request | Returns |
|---|---|
GET /api/runs | The key's calls. |
GET /api/runs/<id> | One call: its lines and speakers. |
GET /api/deferred | Calls recorded for later, and which are ready. |
GET /api/credits | The account's balance and what used it. |
8. Limits and credits
- Each key has its own calls, voices and people. Keys of one account share one credit balance.
- An account's keys may hold a set number of calls open at once (shown on the account page). Waiting in the queue counts.
- A call cannot start on an empty balance. A running call stops by itself when the balance only covers that call's analysis: you get
errorwithcredits, thenstopped. - Revoking a key ends it at once, and every 10-minute token made with it.
9. A minimal client (Python)
import asyncio, json, websockets
async def main():
async with websockets.connect("wss://HOST/v1/listen",
additional_headers={"Authorization": "Bearer pp_..."}) as ws:
await ws.send(json.dumps({"type": "consent", "acknowledged": True, "language": "ar"}))
while True:
m = json.loads(await ws.recv())
if m["type"] == "slot_ready":
await ws.send(json.dumps({"type": "go"}))
elif m["type"] == "ready":
break
elif m["type"] == "error":
raise SystemExit(m["detail"])
async def send():
with open("call.pcm", "rb") as f: # 16 kHz mono int16
while chunk := f.read(640):
await ws.send(chunk)
await asyncio.sleep(0.02) # real time
await ws.send(json.dumps({"type": "stop"}))
asyncio.create_task(send())
async for raw in ws:
m = json.loads(raw)
if m["type"] in ("transcript", "replaced"):
print(m)
if m["type"] == "stopped":
break
asyncio.run(main())
10. Try it: transcribe a file
A complete, runnable client: it converts any audio file with ffmpeg, waits for a slot, streams the audio, prints the lines as they arrive and the final transcript with who spoke. It refuses to run without --acknowledged: you confirm that everyone in the recording knows it is recorded and has agreed.
pip install websockets # and ffmpeg on your PATH
curl -O https://<host>/pages/examples/transcribe_file.py
python transcribe_file.py call.wav --host <host> --key pp_... --language ar --acknowledged
Download transcribe_file.py. Add --speed 4 to stream four times faster than real time while you test.