Speech-to-text API
Two ways to transcribe: a REST endpoint for finished audio, and a realtime WebSocket for live speech.
Two transports
Sprag transcribes speech two ways, with the same models and the same API key. They differ in whether the audio has already finished.
| REST | Realtime | |
|---|---|---|
| Input | A finished audio file | A live audio stream |
| Transport | POST /v1/audio/transcriptions | WebSocket |
| Result arrives | Once, when the whole file is done | In fragments, as each turn ends |
| Word timings | Yes, via timestamps | REST only |
| Speaker labels | Yes, via diarization | REST only |
| Use it for | Recordings, voicemail, uploaded media | Live conversation, captions, meeting notes |
Which to use
Use REST when the audio already exists as a file. It is one request, there is no session to manage, and it is the only path that returns word timings and speaker labels.
Use realtime for a live stream, where one session covers a whole conversation and Sprag finds the turn boundaries for you. Each turn's transcript arrives as the turn closes.
Authentication
Both paths take the same API key. REST sends it as a bearer token.
Authorization: Bearer $SPRAG_API_KEYA client that cannot set that header on a WebSocket upgrade, such as the
browser WebSocket API, passes the key as a subprotocol pair instead:
sprag-api-key followed by the key. Realtime covers
that handshake.
Errors
The two paths report failures differently. REST answers with an HTTP status,
listed on the REST page. A realtime session reports a
rejected event in band as an error event, and closes the socket with a code
when the session cannot continue; Realtime lists
what each code means.
The errors reference has the full error shape and retry guidance.