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); 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 --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
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
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
// 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.
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 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.
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
promptfor continuity. Splitting also keeps you below size and time limits. - Set
languagewhen 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.secondsagainst the length you expect.
For AI agents
- Endpoint: [
POST /audio/transcriptions](https://tokenlane.de/docs/gateway/post-L2F1ZGlvL3RyYW5zY3JpcHRpb25z.md?lang=en), JSON ormultipart/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(jsonorverbose_json),timestamp_granularities(segment,word). - Response:
text,usage.seconds,usage.cost(EUR); withverbose_jsonalsolanguage,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_endpointfor a chat model, 400invalid_parameterwith issue codesmedia_type_mismatch,unsupported_media_type,media_too_large, 413, 402, 408.