Skip to navigation
Paperwork APIRealtime Transcriptions

Create a realtime transcription

View as Markdown

Creates a live transcription session and returns a websocket.url for one client.

Call this from your backend with your API key. Give websocket.url to the browser (or any client). The URL carries a single-use ticket that expires after 60 seconds. The client opens the socket and sends raw PCM16 little-endian audio, 16 kHz, mono, as binary frames. The session sends back partial and final text. The WebSocket upgrade is not an API operation: it is documented on the capability page, not here. Use POST /v1/realtime/transcriptions/{id}/tickets to get a new ticket for a reconnect.

Pricing. A 5-credit session fee, charged when the first decoder joins, or when a session that no client connected to expires. Then 2 credits per started minute of decoded audio. When the session fails on our side (no capacity, no decoder), you pay nothing. With finalPass: true, the batch diarized transcription is billed by the normal audio meters on top (20 credits per minute, minimum 1 minute).

Data. Montreal decode, North America session state, the final pass may run in the US; no residency guarantee. The server keeps no transcript: persist the finals your client receives. Without finalPass, no audio is kept after close.

Limits. A session lasts at most 4 hours (2 hours with finalPass). It closes after 5 minutes without audio. It expires when no client connects within 10 minutes. A revoked API key does not end its live sessions.

MCP code mode can create a session, but it cannot stream audio. Send an idempotency-key: a retry with the same key and body returns the same session with a fresh ticket and the idempotent-replay: true header.

Learn more: Realtime transcription

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

idempotency-keystringOptional1-255 characters
A retry with the same key and body returns the same session.

Request

This endpoint expects an object.
finalPassbooleanOptionalDefaults to false

Archive the audio as a file and run batch diarized transcription at close. Billed by the normal audio meters (minimum 1 diarized minute).

maxDurationSecondsintegerOptional60-14400

Hard cap on received audio. Default and max 14400 (4 h); default and max 7200 with finalPass.

metadatamap from strings to stringsOptional
Kept 30 days after close. Do not put personal data here.

Response

The session, with websocket for the first client.

object"realtime_transcription"
idstring
statusenum
closeReasonenum or null
audioobject
maxDurationSecondsinteger-9007199254740991-9007199254740991
audioSecondsdouble
Received audio, in seconds.
billedMinutesinteger-9007199254740991-9007199254740991
Minutes charged so far.
finalPassobject
metadatamap from strings to strings or null
createdAtdatetime
connectedAtdatetime or null
closedAtdatetime or null
connectBydatetime or null
Connect before this time, or the session expires. Null once a client connected.
websocketobjectOptional
Only in the create response.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error