Personality Psychic · Account

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 receiveMeaningYou may send
queuedposition in the line, waiting in total. Sent again when it changes.{"type":"cancel"} or {"type":"record_later"}
slot_readyA slot is held for you for expires_s seconds (15).{"type":"go"} to start, or the two above
error with expiredNo 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

MessageEffect
{"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

EventFields
speech_started, utterance_endedat_ms
transcriptA first, fast line: text, start_ms, end_ms, speaker, and the tone scores arousal, dominance, valence (may be null).
replacedThe 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.
speakersSpeaker labels changed for the lines in lines.
analysis_windowLive analysis only: the lines being analysed, status: "analysing".
analysisLive analysis only: summary, so_far (the picture of the whole call so far), observations, flags (each with a suggestion; only after me).
meConfirms the speaker you marked.
stoppedThe call is over; carries the call's totals.
errordetail 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:

RequestReturns
GET /api/runsThe key's calls.
GET /api/runs/<id>One call: its lines and speakers.
GET /api/deferredCalls recorded for later, and which are ready.
GET /api/creditsThe account's balance and what used it.

8. Limits and credits

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.