# Transkription für Apps und SaaS-Produkte

> Erweitern Sie Ihr Produkt um Sprachnachrichten, Meeting-Transkripte, Untertitel oder durchsuchbares Audio. Unsere asynchrone REST-API arbeitet in vier Schritten: Datei hochladen, Auftrag starten, Webhook empfangen und Abschnitte speichern.

Zuletzt aktualisiert: 2026-10-18 · HTML: https://console.kolwrite.com/de/use-cases/developers

## Ablauf im Produktivbetrieb

1. Ihr Backend ruft `POST /upload` für die Nutzerdatei auf. Danach gibt es entweder das signierte Formular an den Client weiter oder lädt die Datei selbst hoch (bis zu 100 MiB).
2. Starten Sie den Auftrag und übergeben Sie dabei die erhaltene `fileUrl` als `audio_url` sowie Ihre `webhook_url`.
3. Prüfen Sie zuerst die Webhook-Signatur, filtern Sie Duplikate über `X-KolWrite-Delivery-Id` heraus und rufen Sie anschließend `GET /transcribe/{jobId}` auf, falls `result_omitted` den Wert true hat.
4. Speichern Sie die `segments` (Text, Zeitstempel, Sprecher) für die Anzeige in Ihrer App. Bei Bedarf können Sie das Ergebnis auch als `srt` oder `txt` exportieren.

Auftragsanfrage:

```json
{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}
```

## Webhooks prüfen

```javascript
import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

Zustellungen werden mindestens einmal ausgeführt und bei Fehlern wiederholt. Nutzen Sie `GET /transcribe/{jobId}` als maßgebliche Quelle.

## Modell pro Auftrag wählen

| Produktbedarf | Einstellung | Warum |
| --- | --- | --- |
| Große Mengen an sauberem Audio günstig verarbeiten | `model: "base"` | 0,40 Credits (0,48 US$) pro Stunde |
| Standard für Nutzer-Uploads | `model: "oracle"` | Produktionsqualität, mit Übersetzungsfunktion |
| Transkript in einer anderen Sprache | Oracle-Modell + `translate_to` | Ein Auftrag, direkt übersetzter Text |
| Wer hat was gesagt | `include_diarization: true` | Im Preis enthalten |
| Untertitel | `output_format: "srt"` | Fertig für Videoplayer |

## Technische Limits, die Sie einplanen sollten

- Inline-Base64-Upload: bis zu 4 MiB decodierte Medien. Signierter Upload: bis zu 100 MiB.
- Das signierte Upload-Formular ist 60 Minuten lang gültig, die Lese-URL 24 Stunden.
- Aufträge laufen asynchron ab. Zeigen Sie schon bei `PENDING` und `IN_PROGRESS` den aktuellen Status an.
- `channel_speaker_separation` kann nicht zusammen mit Diarisierung verwendet werden.

## Fragen und Antworten

### Gibt es ein SDK?

Die API nutzt ausschließlich HTTPS und JSON, sodass Sie jeden beliebigen HTTP-Client verwenden können. Für Codegeneratoren steht unter /openapi.json eine OpenAPI-3.1-Datei bereit.

### Wie vermeide ich doppelt verarbeitete Webhooks?

Filtern Sie Duplikate über den Header `X-KolWrite-Delivery-Id` heraus. Bei erneuten Zustellversuchen bleibt diese ID gleich.

### Wie wird die Nutzung abgerechnet?

Pro Sekunde Audio zum Credit-Satz des Modells, ohne Mindestbetrag. 1 Credit kostet 1,20 US$.

## Verwandte Seiten

- [KI-Agenten und Vibe Coding](https://console.kolwrite.com/de/use-cases/ai-agents)
- [Callcenter und Verkaufsgespräche](https://console.kolwrite.com/de/use-cases/call-centers)
- [Unternehmen](https://console.kolwrite.com/de/use-cases/enterprise)
- [Unterstützte Sprachen](https://console.kolwrite.com/de/languages/)

---
API-Schlüssel holen: https://console.kolwrite.com/auth?lang=de · API-Dokumentation: https://console.kolwrite.com/de/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt