# Audio transcription
Turn recorded speech into text: formats, limits, costs and errors of the transcription endpoint.

## When to use it
Meeting recordings, voicemail, interviews, subtitles. `POST /audio/transcriptions` returns the spoken words as text, not an interpretation of them.

Not covered here: a chat model with `audio` input can answer questions about audio sent as an `input_audio` part of a chat message (see [Text and chat](https://tokenlane.de/docs/guides/text-and-chat.md?lang=en)); speech synthesis is not offered.

## Minimal example
JSON with the audio as base64. The example sends a tiny silent WAV file, so it only shows the call; use your own recording for a real result.

### curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/audio/transcriptions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}'
```

### node

```node
const response = await fetch("https://api.tokenlane.de/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
```

### python

```python
import os
import urllib.request

body = (r'''{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/audio/transcriptions",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

### vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
```

The transcript is in `text`; `usage` has the audio duration and the cost.

## Request format
There are two forms with the same fields. Both are validated completely before any provider is called.

JSON (the OpenRouter form): `model`, `input_audio` with `data` and `format`. `data` is plain base64, standard or URL-safe, without a `data:` prefix.

Multipart (the OpenAI form, which OpenAI SDKs send): a `file` part and the other fields as form parts. The format comes from the file extension or the content type of the part.

```bash
curl https://api.tokenlane.de/v1/audio/transcriptions \
  --header "Authorization: Bearer $TOKENLANE_API_KEY" \
  --form model=mistralai/voxtral-mini-transcribe-3-0 --form file=@meeting.mp3 --form language=de
```

| Field | Value |
|---|---|
| `model` | A model that transcribes. A chat model fails with 404 `no_endpoint`. |
| `input_audio.data`, `input_audio.format` | JSON form. Formats: `aac`, `flac`, `m4a`, `mp3`, `mp4`, `mpeg`, `mpga`, `oga`, `ogg`, `opus`, `wav`, `webm`, in any case. |
| `file` | Multipart form. Same formats. |
| `language` | ISO-639-1 code such as `de`. Detected if missing; set it when you know it. |
| `prompt` | Spellings of names and terms, or the end of the previous part. Passed to the provider as sent. |
| `temperature` | 0 to 1. |
| `response_format` | `json` (default): `text` and `usage`. `verbose_json`: also `language`, `duration` and `segments`, as far as the provider returns them. Other values such as `srt` fail. |
| `timestamp_granularities` | `segment` and `word`, with `verbose_json`; `word` adds a `words` array. In multipart: repeat `timestamp_granularities[]`. |

Not supported, with 400 `invalid_parameter`: audio by URL (`input_audio.url`, `source_url`), `diarize: true` and non-empty `keyterms` (put terms into `prompt`).

The formats above are what the gateway accepts. A route can accept fewer, and a route that verifies signatures compares the first bytes with the declared format. Portable on all current routes: `wav`, `mp3`, `flac`, `ogg`, `m4a`, `mp4`, `webm`. `aac`, `opus`, `oga`, `mpeg` and `mpga` can be rejected by a route (`unsupported_media_type`).

Limits:

| Limit | Value | When exceeded |
|---|---|---|
| Body | 50 MiB; as base64 JSON about 37 MiB of audio, as upload nearly 50 MiB | 413 `payload_too_large` |
| File per route | set by the provider; the strictest current routes take 5,000,000 bytes, others 25,000,000 | 400 `invalid_parameter`, issue `media_too_large` |
| Duration | set by the provider; today 15 minutes for the Voxtral routes, 3 hours for Whisper routes | the provider rejects the request; split the recording |
| Response time | 120 s to the first byte, 600 s in total | 408 `timeout` |

Roughly 5,000,000 bytes are 2.6 minutes of WAV (16 kHz, mono, 16 bit: 1.92 MB per minute) or 10 minutes of MP3 at 64 kbit/s.

## Choosing a model
A transcription model takes audio as its only input and returns text; filter the [catalog](https://tokenlane.de/models) by input Audio. Compare the price per second and the providers on the model page. `supported_parameters` shows which of the fields above a model uses; others are dropped and named in `x-ignored-params`. A chat model with audio input is not a transcription model.

## Costs
Transcription routes are priced per second of audio (`pricing.audio_second`, EUR); every started second counts. A route priced per token would bill input and output tokens instead. `usage.seconds` shows the duration billed as the provider reports it (the provider decides how it counts), `usage.cost` the charge in EUR.

A 10-minute recording is billed as 600 seconds, one hour as 3,600 seconds, each times the route's price per second. Current prices are on each model page in the [catalog](https://tokenlane.de/models).

Before the call the gateway reserves the longest audio the route accepts at the price per second: for a Whisper route that is 10,800 seconds, however short the file is.

A key limit or an organization balance below the reservation gets 402 `insufficient_credits`, even for a file of a few seconds. A priced route that reports no duration fails with 502 `provider_invalid_response`; the gateway then tries the next provider.

## Common errors
| Status, type | Cause and fix |
|---|---|
| 404 `no_endpoint` | The model does not transcribe. `remedy_hint` lists models that do. **Fix:** Use one of them. |
| 400 `invalid_parameter` | Missing or empty audio, invalid base64, a `data:` prefix, a format outside the list, `response_format: srt`, `temperature` above 1, URL audio, `diarize`, `keyterms`. **Fix:** Fix every path in `issues`. |
| 400 `invalid_parameter`, issue `media_type_mismatch` | The bytes do not match the declared format. **Fix:** Declare the real format. |
| 400 `invalid_parameter`, issue `unsupported_media_type` or `media_too_large` | The route does not take the format or the size. **Fix:** Convert to `wav` or `mp3`, shorten, or split. |
| 413 `payload_too_large` | Body above 50 MiB. **Fix:** Upload instead of base64, or split. |
| 408 `timeout` | The provider needed too long. **Fix:** Split the recording and retry. |
| 402 `insufficient_credits` | The reservation for the longest accepted audio exceeds the key limit or the credits. **Fix:** Top up credits or raise the key limit. |

## Best practice
- Speech needs little: mono at 16 kHz is enough. Down-mixing and a compressed format such as MP3 shrink the file without hurting accuracy.
- Split long recordings at pauses, a few minutes each, and send the end of the last transcript as `prompt` for continuity. Splitting also keeps you below size and time limits.
- Set `language` when you know it; it avoids wrong detection on short clips.
- Put names, product terms and abbreviations into `prompt`.
- Keep the transcript with your own record ID. Do not log audio.
- Check `usage.seconds` against the length you expect.

## For AI agents
- Endpoint: [`POST /audio/transcriptions`](https://tokenlane.de/docs/gateway/post-L2F1ZGlvL3RyYW5zY3JpcHRpb25z.md?lang=en), JSON or `multipart/form-data`.
- Required (JSON): `model`, `input_audio.data` (base64, no prefix), `input_audio.format`.
- Optional: `language` (ISO-639-1), `prompt`, `temperature` (0 to 1), `response_format` (`json` or `verbose_json`), `timestamp_granularities` (`segment`, `word`).
- Response: `text`, `usage.seconds`, `usage.cost` (EUR); with `verbose_json` also `language`, `duration`, `segments`.
- Limits: body 50 MiB; per route often 5,000,000 bytes; portable formats `wav`, `mp3`, `flac`, `ogg`, `m4a`, `mp4`, `webm`.
- Not supported: audio by URL, `diarize`, `keyterms`.
- Errors: 404 `no_endpoint` for a chat model, 400 `invalid_parameter` with issue codes `media_type_mismatch`, `unsupported_media_type`, `media_too_large`, 413, 402, 408.
