KolWrite KolWrite Entwickler

Die KolWrite-API für KI-Agenten

So lassen Sie einen KI-Agenten (Claude Code, Codex, Cursor oder ein eigenes Skript) Aufnahmen in Transkripte, SRT-Untertitel und Wortzeiten verwandeln – mit der KolWrite-Plattform-API unter https://api-prod.kolwrite.com. Eine Person erstellt einmal ein Token; der Agent liest es aus einer Umgebungsvariablen und ruft schlicht HTTPS auf. Ein SDK ist nicht nötig.

Dies ist die Plattform-API mit kol_-Tokens. Die Credits-API unter https://app.kolwrite.com (Header x-api-key) ist eine andere API und wird (auf Englisch) unter https://console.kolwrite.com/llms.txt beschrieben, falls Sie diese suchen.

Wenn Sie lieber installieren, als die Aufrufe selbst zu schreiben: Die API-Konsole bietet fertige Installationen für die Credits-API, nämlich einen MCP-Server für Claude Code, Codex, Cursor und Gemini CLI, einen Agent-Skill und kolwrite.py, einen Python-Client in einer einzigen Datei. Sie verwenden einen API-Schlüssel von console.kolwrite.com, keinen kol_-Token. Beginnen Sie bei https://console.kolwrite.com/agents/ ; die Dateien sind https://console.kolwrite.com/cli/kolwrite.py und https://console.kolwrite.com/skills/kolwrite-transcribe.zip.

1. Dem Agenten ein Token geben

AufgabeBereiche
Transkribieren und exportierenfiles:write, jobs:write, jobs:read, transcripts:read
Zusätzlich das Credit-Guthaben prüfenbilling:read ergänzen
OpenAI-kompatible Endpunkteai:use (verbraucht Credits; nicht Teil der Voreinstellung Automatisierung der App)
Freigabelinks erstellenshares:write ergänzen

Fügen Sie dies in AGENTS.md, CLAUDE.md oder .cursorrules ein:

## KolWrite platform API
- Base URL https://api-prod.kolwrite.com. The token is in the environment variable KOLWRITE_TOKEN: send it as "Authorization: Bearer $KOLWRITE_TOKEN" and never print it.
- Flow: POST /api/v1/media/upload-session, PUT the bytes to data.upload_url, POST /api/v1/media/complete, POST /api/v1/jobs, poll GET /api/v1/jobs/{job_id} until status is succeeded, then GET /api/v1/jobs/{job_id}/export?format=json
- Spec: https://kolwrite-docs.pages.dev/openapi.json. Guide: https://kolwrite-docs.pages.dev/agents.md

2. Welchen Aufruf Sie wann nutzen

Sie möchtenAufruf
Das Transkript einer Datei, mit Wortzeiten und SprechernUpload-Sitzung, dann POST /api/v1/jobs (type: transcription), dann GET /api/v1/jobs/{job_id}/export?format=json
SRT- oder VTT-UntertitelGET /api/v1/jobs/{job_id}/export?format=srt oder format=vtt
Untertitel in einer anderen Spracheoptions.target_language am Job, dann exportieren
Reinen Textexport?format=text
Word oder PDFexport?format=docx oder format=pdf
Das Transkript, nachdem es in der App korrigiert wurdeGET /api/v1/workspace-files/{workspace_file_id}/transcript?format=json (der Export des Auftrags enthält dieselben Korrekturen)
Nur Transkripte, die als geprüft markiert sindGET /api/v1/workspace-files/{workspace_file_id}/transcript?require_reviewed=true, oder frage GET /api/v1/transcript-reviews?since=...
Ein Aufruf, wenn ein Auftrag fertig ist oder ein Transkript geprüft wurdePOST /api/v1/webhook-endpoints (Bereich webhooks:manage); prüfe KolWrite-Signature
Den Text eines kurzen Sprachclips, ohne JobPOST /api/v1/ai/openai/audio/transcriptions
Chat, Antworten, Embeddings/api/v1/ai/openai/* (OpenAI-kompatible Endpunkte)
Das gespeicherte, versionierte TranskriptGET /api/v1/jobs/{job_id}/artifacts
Das Credit-GuthabenGET /api/v1/billing/balance
Einen öffentlichen Link zu einem TranskriptPOST /api/v1/shares
Welche Modellprofile es gibtGET /api/v1/models

3. Eine Datei in Python transkribieren

import json, mimetypes, os, time
import requests

BASE = "https://api-prod.kolwrite.com"
TOKEN = os.environ["KOLWRITE_TOKEN"]


def call(method, path, **kw):
    headers = {"Authorization": f"Bearer {TOKEN}", **kw.pop("headers", {})}
    r = requests.request(method, BASE + path, headers=headers, timeout=120, **kw)
    r.raise_for_status()
    return r


def transcribe(path, profile="oracle", language="auto"):
    name, size = os.path.basename(path), os.path.getsize(path)
    ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
    session = call("POST", "/api/v1/media/upload-session",
                   json={"filename": name, "file_size_bytes": size,
                         "content_type": ctype}).json()["data"]
    with open(path, "rb") as f:
        requests.put(session["upload_url"], data=f, headers=session["headers"],
                     timeout=3600).raise_for_status()
    media = call("POST", "/api/v1/media/complete",
                 json={"finalize_token": session["finalize_token"]}).json()["data"]
    job = call("POST", "/api/v1/jobs",
               headers={"Idempotency-Key": f"{name}-{size}-{profile}-{language}"},
               json={"type": "transcription",
                     "input": {"type": "media_ref", "media_id": media["media_id"]},
                     "profile": profile,
                     "options": {"language": language,
                                 "diarization": {"mode": "regular"}}}).json()["data"]
    while True:
        status = call("GET", f"/api/v1/jobs/{job['job_id']}").json()["data"]["status"]
        if status in ("succeeded", "failed", "cancelled"):
            break
        time.sleep(5)
    if status != "succeeded":
        raise RuntimeError(f"job {job['job_id']} {status}")
    export = call("GET", f"/api/v1/jobs/{job['job_id']}/export",
                  params={"format": "json"}).json()
    return job["job_id"], json.loads(export["data"])  # data is a JSON string


job_id, transcript = transcribe("interview.wav")
for seg in transcript["segments"]:
    print(f"{seg['start']:.2f}-{seg['end']:.2f} {seg.get('speaker', '')} {seg['text']}")

Große Dateien werden in Teilen hochgeladen: Die Sitzung liefert dann data.upload_url als null und je Teil eine URL in data.multipart_part_urls (siehe Schnellstart).

4. Die Zeiten nutzen

Der JSON-Export enthält segments, jedes mit start und end in Sekunden, text, einem speaker, wenn die Sprechererkennung lief, und words (text, start, end). Lassen Sie den Agenten Segmente nach Index wählen und die Zeiten aus dem Transkript lesen; lassen Sie ein Modell niemals Zeitstempel selbst eintippen.

import subprocess

keep = [s for s in transcript["segments"] if "pricing" in s["text"].lower()]
for i, seg in enumerate(keep):
    subprocess.run(["ffmpeg", "-y", "-i", "talk.mp4", "-ss", str(seg["start"]),
                    "-to", str(seg["end"]), f"clip{i}.mp4"], check=True)

Untertitel kommen direkt aus der API. include_speakers=false lässt die Sprechernamen weg, und max_chars_per_entry legt die Länge jedes Untertiteleintrags fest:

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

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

5. Regeln für Agenten

Fragen

Wie erstelle ich SRT-Untertitel aus einem Video mit einem KI-Agenten?

Laden Sie die Datei hoch, erstellen Sie einen Transkriptionsjob, warten Sie auf succeeded und rufen Sie den Export-Endpunkt mit format=srt auf.

Können Claude Code oder Codex die KolWrite-API aufrufen?

Ja. Sie rufen sie per HTTPS mit einem persönlichen Zugriffstoken aus einer Umgebungsvariablen auf. Es ist weder ein SDK noch ein MCP-Server zu installieren.

Wie bekommt ein Agent Zeitstempel für jedes Wort?

Exportieren Sie den Job als JSON. Jedes Segment enthält words mit start und end in Sekunden.

Markdown-Fassung dieser Seite