KolWrite-API-Dokumentation

Authentifizierung

Alle API-Anfragen müssen mit Ihrem eigenen API-Schlüssel authentifiziert werden. Geben Sie ihn in den Anfrage-Headern an:

x-api-key: YOUR_API_KEY

Ihre API-Schlüssel können Sie in der KolWrite-Konsole erstellen und verwalten, sobald Sie ein Konto angelegt haben.

Schnellstart

Einfache Beispiele für den schnellen Einstieg.

1. Transkription starten

Senden Sie einen POST-Request mit der URL der gewünschten Audiodatei an den Endpunkt `/transcribe`.

Anfrage:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Antwort:

Die API gibt eine `jobId` zurück, über die Sie anschließend das Transkript abrufen.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Transkriptionsergebnis abrufen

Send a GET request bis the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Anfrage:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Antwort (Beispiel):

Sobald der Auftragsstatus COMPLETEDlautet, enthält die Antwort die Details der Transkription.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Modelle und Nutzungs-Credits

Abgerechnet wird sekundengenau in Nutzungs-Credits, ohne Mindestbetrag. Im Checkout, auf Belegen und in Steuerdokumenten steht die tatsächliche Währung, in der Sie bezahlt haben.

1 Credit ist die API-Abrechnungseinheit. In der API-Konsole wurde sie früher als $1.00 angegeben.

Berechtigte israelische Rechnungskonten kaufen Nutzungs-Credits in ILS zu einem Nettopreis von ILS 3.60 pro Credit vor MwSt. Der Checkout zeigt vor der Zahlung die Nutzungs-Credits, den Nettobetrag, die MwSt. und den endgültigen Gesamtbetrag in ILS an. Andere Konten kaufen Nutzungs-Credits in USD zu USD 1.20 pro Credit, sofern keine gesonderten Bestellbedingungen gelten.

Zusätze: Reguläre Sprecher-Diarisierung und standard -Kanaltrennung sind inbegriffen. Die Pro-Sprecher-Diarisierung kostet zusätzlich 0.20 Credits pro Audiostunde. overlap -Kanaltrennung wird zum Satz des gewählten Modells abgerechnet, und zwar für den größeren Wert aus Aufnahmedauer und der über die physischen Kanäle erkannten Gesamtsprechzeit; bei keinem der beiden Kanalmodi fällt ein Diarisierungs-Aufschlag an. Oracle Mini aktiviert die Zeitstempel-Ausrichtung automatisch, wenn Sprecher-Diarisierung oder Kanaltrennung gewählt ist.

API-Endpunkte

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Übergibt eine Audiodatei zur asynchronen Transkription, optional mit Sprecher-Diarisierung.

Parameter des Anfrage-Bodys

Beispielanfrage (mit Diarisierung):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Antwort:

Gibt ein Objekt mit der `jobId` des gesendeten Transkriptionsauftrags zurück.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Ruft Status und Ergebnis eines bestimmten Transkriptionsauftrags ab.

Pfadparameter

Antwort-Body

Beispielantwort (JSON-Ausgabe mit Sprecher-Diarisierung):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Sprecher-Diarisierung

Die Sprecher-Diarisierung erkennt und trennt verschiedene Sprecher in einer Audioaufnahme. Ist sie aktiviert, analysiert KolWrite die Aufnahme, erkennt Sprecherwechsel und versieht jeden Abschnitt mit dem passenden Label.

Sprecher-Diarisierung und Kanaltrennung stehen bei allen aufgeführten Modellen zur Verfügung. Bei Oracle Mini wird automatisch die Zeitstempel-Ausrichtung aktiviert, sobald Sie einen Sprechermodus wählen.

So aktivieren Sie die Diarisierung

Um die Sprecher-Diarisierung zu aktivieren, setzen Sie den Parameter include_diarization auf true in Ihrer Transkriptionsanfrage:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Optimierung der Sprecheranzahl

Geben Sie für beste Ergebnisse die erwartete Anzahl der Sprecher mit dem Parameter num_speakers an. Wenn Sie die genaue Zahl nicht kennen, können Sie:

• Parameter weglassen (wird automatisch erkannt)
• Geben Sie als ungefähren Bereich Ihren besten Schätzwert an

Pro-Diarisierung

Um Sprecher vor allem bei schwieriger Akustik genauer zu erkennen, können Sie die Pro-Diarisierung aktivieren. Das kostet zusätzlich 0.20 Credits pro Audiostunde.

Um sie zu nutzen, setzen Sie den Parameter pro_diarization auf true. Dieser Parameter lässt sich kombinieren mit include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Sprechertrennung nach Kanälen

Bei der Kanaltrennung wird jede physische Audiospur einzeln transkribiert. Zurückgegebene Segmente und Wörter erhalten dabei die jeweiligen physischen Felder channel und speaker. Voraussetzung sind zwei bis acht Kanäle in der audio_url ; sie kann nicht mit der regulären oder der Pro-Diarisierung kombiniert werden. Oracle Mini aktiviert die Zeitstempel-Ausrichtung für beide Kanalmodi automatisch.

Verwenden Sie standard , wenn Sprecher sich abwechseln; abgerechnet wird ein einziger Audiosatz des gewählten Modells. Verwenden Sie overlap , wenn sich Sprecher überschneiden können; abgerechnet wird der Satz des gewählten Modells für den größeren Wert aus Aufnahmedauer und der über die physischen Kanäle erkannten Gesamtsprechzeit.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhooks bei Abschluss

Setzen Sie webhook_url , um transcription.completed und transcription.failed zu erhalten. Fehlgeschlagene Zustellungen werden wiederholt, aber Clients sollten weiterhin GET /transcribe/{jobId} als maßgebliche Quelle unterstützen.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Jede Zustellung enthält X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id und X-KolWrite-Timestamp. Ereignisse werden mindestens einmal zugestellt. Da Wiederholungen dieselbe Zustellungs-ID nutzen, sollten Sie Duplikate herausfiltern anhand von X-KolWrite-Delivery-Id. Ist ein Secret hinterlegt, berechnen Sie HMAC-SHA256 über timestamp + "." + raw_request_body und vergleichen Sie es mit X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

Bei output_format: "json", ist im Webhook das Feld result ein JSON-Objekt. TXT- und SRT-Ergebnisse werden als Strings geliefert.

Bei großen Ergebnissen kann result_omitted auf truegesetzt sein; rufen Sie das vollständige Ergebnis ab über GET /transcribe/{jobId}. Fehlgeschlagene Ereignisse enthalten ein Feld error mit der Fehlermeldung.

Ausgabeformat mit Diarisierung

Wenn die Diarisierung aktiviert ist, enthält jedes Segment der JSON-Ausgabe ein Feld speaker , das den Sprecher kennzeichnet (z. B. „Speaker 1“, „Speaker 2“ usw.).

Ausgabeformate

JSON-Format

Detaillierte Ausgabe mit Segmenten, Zeitstempeln und optionalen Daten auf Wortebene.

TXT-Format

Transkript als reiner Text mit Sprecherlabels (bei aktivierter Diarisierung).

SRT-Format

Das Untertitelformat SubRip mit Zeitstempeln, nutzbar in Videoplayern und Untertitel-Editoren.

Standardmäßig sind Wortzeitstempel aktiv. Die SRT-Datei enthält dann einen Untertitelblock (Cue) pro Wort, wobei jeweils der gesamte Abschnittstext eingeblendet und das gerade gesprochene Wort hervorgehoben wird. Wenn Sie word_timestamps auf false setzen, wird nur ein Block pro Abschnitt erzeugt. WebVTT wird nicht ausgegeben. Bei Bedarf können Sie die SRT-Datei mit ffmpeg konvertieren.

Dienststatus

Sehen Sie sich die öffentliche Statusseite der KolWrite-API an, um Live-Verfügbarkeit, Verfügbarkeitsverlauf und Störungen auf Dienstebene einzusehen.

GET /health benötigt keinen API-Schlüssel und gibt den aktuellen Status von API, Auftragsannahme und Transkriptionsverarbeitung zurück. Eine Antwort 200 bedeutet, dass der Dienst betriebsbereit oder eingeschränkt ist; eine Antwort 503 bedeutet, dass der aktuelle Status unbekannt oder nicht verfügbar ist. Beide Antworten enthalten Statusdetails als JSON.

GET /health/history?period=24h gibt einen kompakten Verfügbarkeitsverlauf zurück. Unterstützte Zeiträume sind 24h, 7d und 30d.

Statuscodes