KolWrite KolWrite Développeurs

L’API KolWrite pour les agents IA

Comment laisser un agent IA (Claude Code, Codex, Cursor ou un script à vous) transformer des enregistrements en transcriptions, sous-titres SRT et horodatages mot à mot avec l’API de plateforme KolWrite, sur https://api-prod.kolwrite.com. Une personne crée un token une seule fois ; l’agent le lit dans une variable d’environnement et appelle simplement HTTPS. Aucun SDK n’est nécessaire.

Voici l’API de plateforme, avec des tokens kol_. L’API de crédits de https://app.kolwrite.com (en-tête x-api-key) est une autre API, décrite (en anglais) sur https://console.kolwrite.com/llms.txt si c’est celle que vous cherchez.

Si vous préférez installer plutôt que d’écrire vous-même les appels, la console de l’API propose des installations prêtes à l’emploi pour l’API de crédits : un serveur MCP pour Claude Code, Codex, Cursor et Gemini CLI, une skill d’agent et kolwrite.py, un client Python d’un seul fichier. Elles utilisent une clé d’API de console.kolwrite.com, pas un token kol_. Commencez sur https://console.kolwrite.com/agents/ ; les fichiers sont https://console.kolwrite.com/cli/kolwrite.py et https://console.kolwrite.com/skills/kolwrite-transcribe.zip.

1. Donner un token à l’agent

TâcheScopes
Transcrire et exporterfiles:write, jobs:write, jobs:read, transcripts:read
Consulter aussi le solde de créditsajoutez billing:read
Endpoints compatibles OpenAIai:use (consomme des crédits ; absent du préréglage Automation de l’app)
Créer des liens de partageajoutez shares:write

Collez ceci dans AGENTS.md, CLAUDE.md ou .cursorrules :

## 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. Quel appel utiliser

Vous voulezAppel
La transcription d’un fichier, avec horodatage des mots et locuteurssession d’envoi, puis POST /api/v1/jobs (type: transcription), puis GET /api/v1/jobs/{job_id}/export?format=json
Des sous-titres SRT ou VTTGET /api/v1/jobs/{job_id}/export?format=srt ou format=vtt
Des sous-titres dans une autre langueoptions.target_language sur le job, puis export
Du texte brutexport?format=text
Word ou PDFexport?format=docx ou format=pdf
La transcription après correction dans l'applicationGET /api/v1/workspace-files/{workspace_file_id}/transcript?format=json (l'export de la tâche inclut les mêmes corrections)
Uniquement les transcriptions marquées comme reluesGET /api/v1/workspace-files/{workspace_file_id}/transcript?require_reviewed=true, ou interrogez GET /api/v1/transcript-reviews?since=...
Un appel quand une tâche se termine ou qu'une transcription est reluePOST /api/v1/webhook-endpoints (portée webhooks:manage) ; vérifiez KolWrite-Signature
Le texte d’un court clip vocal, sans jobPOST /api/v1/ai/openai/audio/transcriptions
Chat, réponses, embeddings/api/v1/ai/openai/* (endpoints compatibles OpenAI)
La transcription enregistrée, avec ses versionsGET /api/v1/jobs/{job_id}/artifacts
Le solde de créditsGET /api/v1/billing/balance
Un lien public vers une transcriptionPOST /api/v1/shares
Quels profils de modèle existentGET /api/v1/models

3. Transcrire un fichier en Python

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']}")

Les fichiers volumineux sont envoyés en plusieurs parties : la session renvoie alors data.upload_url à null et une URL par partie dans data.multipart_part_urls (voir le démarrage rapide).

4. Exploiter les horodatages

L’export JSON contient segments, chacun avec start et end en secondes, text, un speaker quand la diarisation a tourné, et words (text, start, end). Laissez l’agent choisir des segments par indice et lire les temps dans la transcription ; ne le laissez jamais saisir lui-même des horodatages.

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)

Les sous-titres viennent directement de l’API. include_speakers=false retire les noms des locuteurs, et max_chars_per_entry fixe la longueur de chaque entrée de sous-titre :

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"

Le téléchargement des SRT et VTT est gratuit dans toutes les offres.

5. Règles pour les agents

Questions

Comment créer des sous-titres SRT à partir d’une vidéo avec un agent IA ?

Envoyez le fichier, créez un job de transcription, attendez succeeded, puis appelez l’endpoint d’export avec format=srt.

Claude Code ou Codex peuvent-ils appeler l’API KolWrite ?

Oui. Ils l’appellent en HTTPS avec un token d’accès personnel pris dans une variable d’environnement. Il n’y a ni SDK ni serveur MCP à installer.

Comment un agent obtient-il l’horodatage de chaque mot ?

Exportez le job en JSON. Chaque segment porte words avec start et end en secondes.

Version Markdown de cette page