# 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](https://tokenlane.de/docs/guides/text-and-chat.md?lang=de)); 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
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());
```

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.

```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
```

| Feld | Wert |
|---|---|
| `model` | Ein Modell, das transkribiert. Ein Chat-Modell scheitert mit 404 `no_endpoint`. |
| `input_audio.data`, `input_audio.format` | JSON-Form. Formate: `aac`, `flac`, `m4a`, `mp3`, `mp4`, `mpeg`, `mpga`, `oga`, `ogg`, `opus`, `wav`, `webm`, in beliebiger Schreibweise. |
| `file` | Multipart-Form. Dieselben Formate. |
| `language` | ISO-639-1-Code wie `de`. Wird erkannt, wenn er fehlt; setzen, wenn bekannt. |
| `prompt` | Schreibweisen von Namen und Begriffen oder das Ende des vorherigen Teils. Wird unverändert an den Anbieter gereicht. |
| `temperature` | 0 bis 1. |
| `response_format` | `json` (Standard): `text` und `usage`. `verbose_json`: zusätzlich `language`, `duration` und `segments`, soweit der Anbieter sie liefert. Andere Werte wie `srt` scheitern. |
| `timestamp_granularities` | `segment` 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:

| Grenze | Wert | Bei Überschreitung |
|---|---|---|
| Body | 50 MiB; als Base64-JSON etwa 37 MiB Audio, als Upload fast 50 MiB | 413 `payload_too_large` |
| Datei je Route | vom Anbieter festgelegt; die strengsten heutigen Routen nehmen 5.000.000 Bytes, andere 25.000.000 | 400 `invalid_parameter`, Issue `media_too_large` |
| Dauer | vom Anbieter festgelegt; heute 15 Minuten bei den Voxtral-Routen, 3 Stunden bei Whisper-Routen | der Anbieter lehnt ab; die Aufnahme teilen |
| Antwortzeit | 120 s bis zum ersten Byte, 600 s insgesamt | 408 `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](https://tokenlane.de/models) 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](https://tokenlane.de/models).

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, Typ | Ursache und Abhilfe |
|---|---|
| 404 `no_endpoint` | Das Modell transkribiert nicht. `remedy_hint` listet Modelle, die es tun. **Abhilfe:** Eines davon nutzen. |
| 400 `invalid_parameter` | Fehlendes 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_mismatch` | Die Bytes passen nicht zum angegebenen Format. **Abhilfe:** Das tatsächliche Format angeben. |
| 400 `invalid_parameter`, Issue `unsupported_media_type` oder `media_too_large` | Die Route nimmt Format oder Größe nicht. **Abhilfe:** In `wav` oder `mp3` umwandeln, kürzen oder teilen. |
| 413 `payload_too_large` | Body über 50 MiB. **Abhilfe:** Hochladen statt Base64, oder teilen. |
| 408 `timeout` | Der Anbieter brauchte zu lange. **Abhilfe:** Die Aufnahme teilen und wiederholen. |
| 402 `insufficient_credits` | Die 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.
