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
FieldValue
modelA model that transcribes. A chat model fails with 404 no_endpoint.
input_audio.data, input_audio.formatJSON form. Formats: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav, webm, in any case.
fileMultipart form. Same formats.
languageISO-639-1 code such as de. Detected if missing; set it when you know it.
promptSpellings of names and terms, or the end of the previous part. Passed to the provider as sent.
temperature0 to 1.
response_formatjson (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_granularitiessegment 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:

LimitValueWhen exceeded
Body50 MiB; as base64 JSON about 37 MiB of audio, as upload nearly 50 MiB413 payload_too_large
File per routeset by the provider; the strictest current routes take 5,000,000 bytes, others 25,000,000400 invalid_parameter, issue media_too_large
Durationset by the provider; today 15 minutes for the Voxtral routes, 3 hours for Whisper routesthe provider rejects the request; split the recording
Response time120 s to the first byte, 600 s in total408 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, typeCause and fix
404 no_endpointThe model does not transcribe. remedy_hint lists models that do. Fix: Use one of them.
400 invalid_parameterMissing 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_mismatchThe bytes do not match the declared format. Fix: Declare the real format.
400 invalid_parameter, issue unsupported_media_type or media_too_largeThe route does not take the format or the size. Fix: Convert to wav or mp3, shorten, or split.
413 payload_too_largeBody above 50 MiB. Fix: Upload instead of base64, or split.
408 timeoutThe provider needed too long. Fix: Split the recording and retry.
402 insufficient_creditsThe 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.