KolWrite KolWrite Entwickler

KolWrite-API: Schnellstart

Automatisieren Sie alles, was Sie in der KolWrite-App tun: eine Datei hochladen, mit allen Optionen transkribieren, das Transkript exportieren und teilen – mit einem persönlichen Zugriffstoken (PAT).

Basis-URL: https://api-prod.kolwrite.com

1. Token erstellen

Der API-Zugriff ist Self-Service: Sobald Ihr Konto Credits gekauft hat, schalten Sie ihn unter Einstellungen → Konto → API-Zugriff ein. Aufrufe verbrauchen Ihre Credits.

In der KolWrite-App: Einstellungen → Konto → API-Zugriff → Token erstellen. Wählen Sie die Berechtigungsbereiche, die Sie brauchen (diese Anleitung verwendet files:write, jobs:write, jobs:read, transcripts:read). Das Geheimnis (kol_...) wird nur einmal angezeigt – bewahren Sie es sicher auf.

Senden Sie es mit jeder Anfrage:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/billing/balance

2. Datei hochladen

Erstellen Sie eine Upload-Sitzung, senden Sie die Bytes per PUT an die vorsignierte URL und schließen Sie den Upload dann ab:

# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api-prod.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api-prod.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id

Große Dateien werden in Teilen hochgeladen: Die Sitzung liefert dann data.upload_url als null und eine URL je Teil in data.multipart_part_urls. Senden Sie jeden Teil per PUT, merken Sie sich den Header ETag jeder Antwort und übergeben Sie diese beim Abschluss als uploaded_parts: eine Liste von Objekten der Form {part_number, etag}.

3. Transkribieren

Erstellen Sie einen Job. profile wählt die Modellstufe (oracle, oracle-mini, oracle-pro, oracle-max – Auflistung über GET /api/v1/models); options enthält alles, was der Analysedialog der App bietet. Verwenden Sie einen Idempotency-Key, damit Wiederholungen nie doppelt abgeschickt werden:

curl -X POST https://api-prod.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"

Das Einbrennen von Untertiteln funktioniert genauso mit "type": "caption_burn" und einem Stilblock options.caption_burn – siehe Referenz.

4. Auf das Ergebnis warten

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting

5. Transkript exportieren

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

Formate: text, json, srt, vtt, docx, pdf. Der Export ist das Transkript, wie es jetzt ist: Korrekturen im KolWrite-Editor sind enthalten, sobald sie gespeichert sind, ohne zusätzlichen Schritt.

Um das aktuelle Transkript einer Datei über ihre Workspace-Datei-ID zu lesen (derselbe Text wie in der App), nutze GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json mit dem Bereich transcripts:read. Die Header X-Transcript-Version-Id und X-Transcript-Revision ändern sich, sobald sich das Transkript ändert; ein abfragendes Skript erkennt so, wann es etwas Neues gibt. Gespeicherte Versionen liegen unter GET /api/v1/jobs/JOB_ID/artifacts und GET /api/v1/artifacts/{artifact_id}; eine gespeicherte Version ist ein fester Stand ohne spätere Änderungen.

Um nur Transkripte abzuholen, die ein Mensch freigegeben hat, lass die Prüfenden im Editor auf "Als geprüft markieren" tippen. Danach sendet der Transkript-Aufruf X-Transcript-Review-Status: reviewed bis zur nächsten Änderung, und require_reviewed=true lässt ihn sonst mit 409 transcript_not_reviewed antworten. GET /api/v1/transcript-reviews?since=... listet Dateien, die seit deiner letzten Abfrage geprüft wurden. Oder ganz ohne Abfragen: Lege mit POST /api/v1/webhook-endpoints (Bereich webhooks:manage) einen Webhook für transcript.reviewed, job.completed, job.failed, upload.completed oder upload.failed an und prüfe bei jeder Anfrage den Header KolWrite-Signature (HMAC-SHA256 von <t>.<raw body> mit dem Geheimnis des Endpunkts).

Der Download von SRT und VTT ist in jedem Tarif kostenlos.

6. Optional: teilen

Mit shares:write:

curl -X POST https://api-prod.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url

Weiter

Markdown-Fassung dieser Seite