Audio-Transkription

Gesprochene Sprache in Text umwandeln: Formate, Grenzen, Kosten und Fehler des Transkriptions-Endpunkts.

Wann nutzen

Besprechungsaufnahmen, Sprachnachrichten, Interviews, Untertitel. POST /audio/transcriptions liefert die gesprochenen Wörter als Text, keine Deutung davon.

Nicht Gegenstand dieses Leitfadens: Ein Chat-Modell mit audio-Eingabe kann Fragen zu Audio beantworten, das als input_audio-Teil einer Chat-Nachricht gesendet wird (siehe Text und Chat); Sprachsynthese wird nicht angeboten.

Minimalbeispiel

JSON mit dem Audio als Base64. Das Beispiel sendet eine winzige stille WAV-Datei und zeigt deshalb nur den Aufruf; für ein echtes Ergebnis eine eigene Aufnahme verwenden.

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());

Das Transkript steht in text; usage enthält die Audiodauer und die Kosten.

Anfrageformat

Es gibt zwei Formen mit denselben Feldern. Beide werden vollständig geprüft, bevor ein Anbieter aufgerufen wird.

JSON (die OpenRouter-Form): model, input_audio mit data und format. data ist reines Base64, Standard- oder URL-sicher, ohne data:-Präfix.

Multipart (die OpenAI-Form, die OpenAI-SDKs senden): ein file-Teil und die übrigen Felder als Formularteile. Das Format ergibt sich aus der Dateiendung oder dem Content-Type des Teils.

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
FeldWert
modelEin Modell, das transkribiert. Ein Chat-Modell scheitert mit 404 no_endpoint.
input_audio.data, input_audio.formatJSON-Form. Formate: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav, webm, in beliebiger Schreibweise.
fileMultipart-Form. Dieselben Formate.
languageISO-639-1-Code wie de. Wird erkannt, wenn er fehlt; setzen, wenn bekannt.
promptSchreibweisen von Namen und Begriffen oder das Ende des vorherigen Teils. Wird unverändert an den Anbieter gereicht.
temperature0 bis 1.
response_formatjson (Standard): text und usage. verbose_json: zusätzlich language, duration und segments, soweit der Anbieter sie liefert. Andere Werte wie srt scheitern.
timestamp_granularitiessegment und word, mit verbose_json; word ergänzt ein words-Array. Bei Multipart timestamp_granularities[] wiederholen.

Nicht unterstützt, mit 400 invalid_parameter: Audio per URL (input_audio.url, source_url), diarize: true und nicht leere keyterms (Begriffe in prompt schreiben).

Die obigen Formate nimmt das Gateway an. Eine Route kann weniger akzeptieren, und eine Route mit Signaturprüfung vergleicht die ersten Bytes mit dem angegebenen Format. Übertragbar auf allen heutigen Routen: wav, mp3, flac, ogg, m4a, mp4, webm. aac, opus, oga, mpeg und mpga kann eine Route ablehnen (unsupported_media_type).

Grenzen:

GrenzeWertBei Überschreitung
Body50 MiB; als Base64-JSON etwa 37 MiB Audio, als Upload fast 50 MiB413 payload_too_large
Datei je Routevom Anbieter festgelegt; die strengsten heutigen Routen nehmen 5.000.000 Bytes, andere 25.000.000400 invalid_parameter, Issue media_too_large
Dauervom Anbieter festgelegt; heute 15 Minuten bei den Voxtral-Routen, 3 Stunden bei Whisper-Routender Anbieter lehnt ab; die Aufnahme teilen
Antwortzeit120 s bis zum ersten Byte, 600 s insgesamt408 timeout

Etwa 5.000.000 Bytes sind 2,6 Minuten WAV (16 kHz, mono, 16 Bit: 1,92 MB je Minute) oder 10 Minuten MP3 mit 64 kbit/s.

Modell wählen

Ein Transkriptionsmodell nimmt nur Audio als Eingabe und liefert Text; den Katalog nach Eingabe Audio filtern. Preis je Sekunde und Anbieter auf der Modellseite vergleichen. supported_parameters zeigt, welche der obigen Felder ein Modell nutzt; andere werden weggelassen und in x-ignored-params genannt. Ein Chat-Modell mit Audioeingabe ist kein Transkriptionsmodell.

Kosten

Transkriptionsrouten werden je Sekunde Audio berechnet (pricing.audio_second, EUR); jede angefangene Sekunde zählt. Eine Route mit Tokenpreis würde stattdessen Eingabe- und Ausgabe-Tokens berechnen. usage.seconds zeigt die abgerechnete Dauer, wie der Anbieter sie meldet (der Anbieter bestimmt, wie er zählt), usage.cost den Betrag in EUR.

Eine Aufnahme von 10 Minuten wird als 600 Sekunden abgerechnet, eine Stunde als 3.600 Sekunden, jeweils mal dem Sekundenpreis der Route. Die aktuellen Preise stehen auf jeder Modellseite im Katalog.

Vor dem Aufruf reserviert das Gateway das längste Audio, das die Route annimmt, zum Preis je Sekunde: Bei einer Whisper-Route sind das 10.800 Sekunden, egal wie kurz die Datei ist.

Liegt ein Key-Limit oder Organisationsguthaben unter der Reservierung, folgt 402 insufficient_credits, auch bei einer Datei von wenigen Sekunden. Meldet eine bepreiste Route keine Dauer, scheitert die Anfrage mit 502 provider_invalid_response; das Gateway versucht dann den nächsten Anbieter.

Häufige Fehler

Status, TypUrsache und Abhilfe
404 no_endpointDas Modell transkribiert nicht. remedy_hint listet Modelle, die es tun. Abhilfe: Eines davon nutzen.
400 invalid_parameterFehlendes oder leeres Audio, ungültiges Base64, ein data:-Präfix, ein Format außerhalb der Liste, response_format: srt, temperature über 1, URL-Audio, diarize, keyterms. Abhilfe: Jeden Pfad in issues korrigieren.
400 invalid_parameter, Issue media_type_mismatchDie Bytes passen nicht zum angegebenen Format. Abhilfe: Das tatsächliche Format angeben.
400 invalid_parameter, Issue unsupported_media_type oder media_too_largeDie Route nimmt Format oder Größe nicht. Abhilfe: In wav oder mp3 umwandeln, kürzen oder teilen.
413 payload_too_largeBody über 50 MiB. Abhilfe: Hochladen statt Base64, oder teilen.
408 timeoutDer Anbieter brauchte zu lange. Abhilfe: Die Aufnahme teilen und wiederholen.
402 insufficient_creditsDie Reservierung für das längste akzeptierte Audio übersteigt das Key-Limit oder das Guthaben. Abhilfe: Guthaben aufladen oder das Key-Limit erhöhen.

Bewährte Praxis

  • Sprache braucht wenig: Mono bei 16 kHz genügt. Herunterrechnen auf Mono und ein komprimiertes Format wie MP3 verkleinern die Datei, ohne die Genauigkeit zu mindern.
  • Lange Aufnahmen an Pausen teilen, je einige Minuten, und das Ende des letzten Transkripts als prompt für den Zusammenhang mitsenden. Das Teilen hält auch Größen- und Zeitgrenzen ein.
  • language setzen, wenn sie bekannt ist; das vermeidet falsche Erkennung bei kurzen Clips.
  • Namen, Fachbegriffe und Abkürzungen in prompt schreiben.
  • Das Transkript mit einer eigenen Datensatz-ID aufbewahren. Audio nicht loggen.
  • usage.seconds mit der erwarteten Länge vergleichen.

Für KI-Agenten

  • Endpunkt: [POST /audio/transcriptions](https://tokenlane.de/docs/gateway/post-L2F1ZGlvL3RyYW5zY3JpcHRpb25z.md?lang=de), JSON oder multipart/form-data.
  • Pflicht (JSON): model, input_audio.data (Base64, ohne Präfix), input_audio.format.
  • Optional: language (ISO-639-1), prompt, temperature (0 bis 1), response_format (json oder verbose_json), timestamp_granularities (segment, word).
  • Antwort: text, usage.seconds, usage.cost (EUR); mit verbose_json zusätzlich language, duration, segments.
  • Grenzen: Body 50 MiB; je Route oft 5.000.000 Bytes; übertragbare Formate wav, mp3, flac, ogg, m4a, mp4, webm.
  • Nicht unterstützt: Audio per URL, diarize, keyterms.
  • Fehler: 404 no_endpoint bei einem Chat-Modell, 400 invalid_parameter mit den Issue-Codes media_type_mismatch, unsupported_media_type, media_too_large, 413, 402, 408.