API reference · Transcribe

Stream audio in, get the transcript back

POST /api/v1/transcribe

Send the audio as the request body and receive an SSE stream that ends with the transcript. Use it from shells and simple scripts. For files over 200 MB, use an SDK, which uploads the file for you. Rate limit: 120 requests per minute.

The first event is accepted. It carries the job_id and a download_url and is sent immediately, so you can retrieve the job if your connection drops. The X-Job-Id response header carries the same id. Next come the job's progress events, as on the jobs stream. These are best effort: when the stream pool is saturated you get waiting heartbeats with an ETA instead. Then comes completed with {"download_url": ...}, and finally transcript, whose data is the result in the requested output_type (one data: line per line of output). A failed job ends with failed. If the wait limit is reached, the stream ends with timeout; if the result cannot be read back, it ends with error. Both carry job_id and download_url, so you can still fetch the result.

Send your API key in the X-API-Key header. See Authentication.

Query parameters

  • model string default: zephyr

    The transcription model. There is currently one.

  • output_type string default: json

    Format of the stored transcript at download_url.

    One of json, txt, srt, vtt, docx, pdf

  • word_timestamps boolean default: true
  • speaker_labels boolean default: true
  • nltk boolean default: true

    Punctuation and sentence segmentation.

  • custom_vocabulary string

    Domain terms to bias recognition towards, as one comma-separated string.

  • language string

    ISO 639-1 code of the spoken language, from the 99 supported languages (e.g. en, ru, de). Omit it, or pass auto, for automatic language detection (the default), which also handles audio that switches language mid-file. When you set a language, detection is skipped and the whole file is transcribed in that language. Setting the wrong language translates the audio into it (Russian audio sent with en comes back as an English translation) and disables mid-file language switching. An unsupported code returns 422 with a message naming the bad value.

  • callback_url string (uri)

    Webhook URL to POST to when the job completes or fails permanently.

Request body

Required. The raw file bytes — send the file itself, not JSON. Accepted types: audio/mpeg, audio/wav, audio/mp4, audio/ogg, audio/flac, video/mp4, application/octet-stream.

Responses

  • 200 An event stream ending in the transcript.
  • 401 Missing, malformed or revoked API key.
  • 402 The account is out of credit. Top up, or turn on auto-recharge, and retry. Reads and cancellations keep working.
  • 413 The file exceeds the limit for this route: 10 GB through the upload routes, 200 MB streaming to /api/v1/transcribe.
  • 422 A field is missing or the wrong type. The body names the offending field.
  • 429 Too many requests for this endpoint. Back off and retry; the official SDKs do this for you.