Transcribe audio (beta)

Cloud transcription through the API is in beta. Limits, response shape, and availability may change, and there is no SLA. For long recordings or free, private transcription, use the OpenWhispr CLI with the desktop app running.

POST /transcribe takes an audio file and returns its transcript in the same response — no polling, no job id. It’s built for short clips: a voice memo, a message, a single answer in a form. For anything long, or anything you’d rather keep on your own machine, see Use the CLI for local transcription below.

Requirements

A Pro or Business plan. Cloud transcription is a paid feature; local transcription in the desktop app and CLI is free on every plan.
A personal API key (owk_live_) carrying the transcriptions:write scope. A workspace key gets 403.
An audio file of 4 MB or less in one of: wav, mp3, m4a/mp4, ogg, flac, webm.

Request

Send multipart/form-data:

Field	Required	Description
`file`	Yes	The audio file.
`language`	No	Language code of the audio, e.g. `en`.
`prompt`	No	Names and jargon to spell correctly, comma-separated — the same job your dictionary does in the app.

curl -X POST https://api.openwhispr.com/api/v1/transcribe \
  -H "Authorization: Bearer owk_live_YOUR_KEY" \
  -F "file=@memo.m4a" \
  -F "language=en" \
  -F "prompt=OpenWhispr, Siobhán, ARR"

Response

{
  "data": {
    "id": "...",
    "text": "Quick reminder to send Siobhán the ARR numbers before the OpenWhispr sync.",
    "language": "en",
    "duration_ms": 6420,
    "words": 13,
    "provider": "...",
    "model": "...",
    "beta": true
  }
}

Field	Description
`id`	Id of the transcription.
`text`	The transcript.
`language`	Language of the transcript.
`duration_ms`	Length of the audio in milliseconds, estimated from the file size when the engine doesn’t report it. This is what counts against your monthly minutes.
`words`	Word count of the transcript.
`provider`, `model`	Which engine produced it. Informational, and may change during the beta.
`beta`	Always `true` while the endpoint is in beta. When it stops being `true`, check this page — the shape may have changed.

The response carries no timestamps, so there is nothing to build subtitles from. Timestamped output is not available in the beta.

Limits

Limit	Value
File size	4 MB per request
Audio	600 minutes per calendar month
Concurrency	One transcription at a time per key
Rate-limit cost	Each call counts as 5 requests against the key’s per-minute and per-day rate limits

On Pro (120 requests a minute) that’s at most 24 transcriptions a minute before 429 rate_limited, assuming the key does nothing else.

Errors

HTTP status	Code	Meaning
400	`validation_error`	Missing `file`, a format not in the list above, or a bad field value.
403	`plan_required`	Your plan is Free. Upgrade to Pro or Business, or transcribe locally with the CLI for free.
403	`forbidden`	The key lacks `transcriptions:write`, it’s a workspace key, or your organization’s policy blocks cloud transcription. The `message` says which.
409	`concurrency_limit`	A transcription is already running on this key. Wait for it to finish, then retry.
413	`payload_too_large`	The file is over 4 MB. Split it, or use the CLI, which splits for you.
429	`quota_exceeded`	You’ve used 600 audio minutes this calendar month. The message includes the date the quota resets.
429	`rate_limited`	The key’s per-minute or per-day request limit. Wait for `Retry-After`.
503	`service_unavailable`	The beta is paused. Nothing is wrong with your request — retry later.

Errors use the standard { "error": { "code", "message" } } envelope — see Errors.

Use the CLI for local transcription

With the desktop app running, the OpenWhispr CLI transcribes on your machine with whatever local model the app is set to use. It’s free, there’s no 4 MB cap or monthly quota, and the audio never leaves the machine.

openwhispr transcribe recording.m4a
openwhispr transcribe interview.wav --format json > interview.json

Pass --remote to send the file to OpenWhispr Cloud instead; the CLI then uses this endpoint, with the same plan and scope requirements, and splits files over 4 MB into chunks for you. See transcribe in the command reference.

Overview

CLI

Integrations

Open source

Transcribe audio (beta)

Requirements

Request

Response

Limits

Errors

Use the CLI for local transcription

​Requirements

​Request

​Response

​Limits

​Errors

​Use the CLI for local transcription

Requirements

Request

Response

Limits

Errors

Use the CLI for local transcription