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.kolwrite.com

1. Token erstellen

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.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.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.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.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.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.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

Formate: text, json, srt, vtt. Dauerhafte Transkript-Artefakte (mit Versionsverlauf) sind unter GET /api/v1/jobs/JOB_ID/artifacts und GET /api/v1/artifacts/{artifact_id} verfügbar, mit dem Bereich transcripts:read.

Der Download von SRT und VTT setzt einen Plus-Tarif oder höher voraus; andere Tarife erhalten HTTP 403 mit dem Code subtitle_export_requires_plus.

6. Optional: teilen

Mit shares:write:

curl -X POST https://api.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