Transcribe API (terminal)

Send audio in one request and get the transcript back on the same connection. Use it from shells and simple scripts.

POST /api/v1/transcribe

Designed for cURL

Use this endpoint from the terminal. In application code, use an SDK.

Request

The request body is the raw audio bytes. Transcription options are query parameters (see the endpoint reference).

bash

curl -N -X POST \
  "https://api.speechrevolutions.com/api/v1/transcribe?output_type=json&word_timestamps=true&speaker_labels=true&nltk=true&custom_vocabulary=AcmeCorp,Grok" \
  -H "X-API-Key: $SPEECHREVOLUTIONS_API_KEY" \
  --data-binary @audio.mp3

Behavior

You stream the raw audio bytes as the request body.
The server creates the job and immediately sends an accepted event. It carries the job_id (also in the X-Job-Id response header), a download_url, and a ready-made resume command. If your connection drops, use these to fetch the job you started.
It then sends the job's progress events, identical to the Jobs SSE stream (completed/total/step; the first one already has completed ≥ 1). Files under about 3 MiB are processed in a single pass and usually send no progress events. Progress is best effort: when progress is unavailable, you get a waiting heartbeat with an ETA instead.
On success, it sends completed (data: {"download_url": "…"}), then a final transcript event whose data is the finished result in your output_type. Multi-line output is sent as one data: field per line, which SSE clients join back together.

Events

A short file, as streamed (URLs shortened):

text

event: accepted
data: {"job_id": "57dd9d88-676a-43e4-a96c-c31e68859f90", "download_url": "https://…", "llm_download_url": null, "resume": "curl -H \"X-API-Key: $SPEECHREVOLUTIONS_API_KEY\" https://api.speechrevolutions.com/api/v1/jobs/57dd9d88-676a-43e4-a96c-c31e68859f90"}

id: 1791179346392-0
event: completed
data: {"download_url": "https://…"}

event: transcript
data: {"words": [{"word": "Ребят,", "start": 0.12, "end": 0.34, "speaker": "SPEAKER_1", …}, …], …}

A longer file also reports its steps between the two:

text

id: 1791179526032-0
event: progress
data: {"completed": 1, "total": 7, "step": "preprocess"}

id: 1791179533242-0
event: progress
data: {"completed": 2, "total": 7, "step": "chunk:0"}

…

id: 1791179547620-0
event: progress
data: {"completed": 7, "total": 7, "step": "aggregation"}

Event	Data
`accepted`	`job_id`, `download_url`, `llm_download_url`, `resume`. Always first.
`progress`	`{"completed": <int>, "total": <int>, "step": "<name>"}`
`waiting`	Heartbeat while progress is unavailable. Ignore it or show the ETA.
`completed`	`{"download_url": "<url>"}`. The `transcript` event follows.
`transcript`	The result itself, in the requested `output_type`. Last event.
`failed`	The job failed; `{"step": "<name>", "reason": "<msg>"}`. Last event.
`timeout` / `error`	The wait limit was reached, or the finished result could not be read back. Both carry `job_id` and `download_url`. Fetch the result from `download_url`.

Errors

Status	Meaning
`401`	Missing or invalid API key
`413`	File too large for this endpoint
`422`	Invalid query parameter, e.g. an unsupported `language` code
`429`	Rate limit exceeded

Guide: Terminal & cURL