> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openwhispr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcribe audio (beta)

> Send a short audio file to OpenWhispr Cloud and get the transcript back in one request.

<Warning>
  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.
</Warning>

`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](#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](/api/workspace-keys) 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](/api/dictionary-and-snippets) does in the app. |

```bash theme={null}
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

```json theme={null}
{
  "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](/api/overview#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](/api/errors).

## Use the CLI for local transcription

With the desktop app running, the [OpenWhispr CLI](/cli/install) transcribes on your machine with whatever [local model](/guides/local-models) 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.

```bash theme={null}
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`](/cli/commands#transcribe) in the command reference.