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.

API-Schlüssel holen Schnellstart Unterstützte Sprachen

Zuletzt aktualisiert: · Markdown

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:

{
  "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

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

ProduktbedarfEinstellungWarum
Große Mengen an sauberem Audio günstig verarbeitenmodel: "base"0,40 Credits (0,48 US$) pro Stunde
Standard für Nutzer-Uploadsmodel: "oracle"Produktionsqualität, mit Übersetzungsfunktion
Transkript in einer anderen SpracheOracle-Modell + translate_toEin Auftrag, direkt übersetzter Text
Wer hat was gesagtinclude_diarization: trueIm Preis enthalten
Untertiteloutput_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