KolWrite KolWrite Développeurs

Démarrage rapide de l’API KolWrite

Automatisez tout ce que vous faites dans l’application KolWrite — importer un fichier, le transcrire avec toutes les options, exporter la transcription et la partager — à l’aide d’un token d’accès personnel (PAT).

URL de base : https://api-prod.kolwrite.com

1. Créer un token

L’accès à l’API est en libre-service : dès que votre compte a acheté des crédits, activez-le dans Paramètres → Compte → Accès à l’API. Les appels consomment vos crédits.

Dans l’application KolWrite : Paramètres → Compte → Accès à l’API → Créer un token. Choisissez les scopes nécessaires (ce guide utilise files:write, jobs:write, jobs:read, transcripts:read). Le secret (kol_...) ne s’affiche qu’une fois — conservez-le en lieu sûr.

Envoyez-le avec chaque requête :

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

2. Importer un fichier

Créez une session d’import, envoyez les octets avec PUT vers l’URL présignée, puis finalisez :

# 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

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. Envoyez chaque partie avec PUT, conservez l’en-tête ETag de chaque réponse et transmettez-les à l’appel de finalisation sous uploaded_parts : une liste d’objets {part_number, etag}.

3. Le transcrire

Créez un job. profile sélectionne le niveau de modèle (oracle, oracle-mini, oracle-pro, oracle-max — répertoriez-les avec GET /api/v1/models) ; options contient tous les réglages proposés dans la boîte de dialogue Analyser de l’application. Utilisez une Idempotency-Key afin que les nouvelles tentatives ne soumettent jamais le job en double :

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"

L’incrustation de sous-titres fonctionne de la même manière avec "type": "caption_burn" et un bloc de style options.caption_burn — consultez la référence.

4. Interroger jusqu’à la fin

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. Exporter la transcription

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

Formats : text, json, srt, vtt, docx, pdf. L'export est la transcription telle qu'elle est maintenant : les corrections faites dans l'éditeur KolWrite sont incluses dès qu'elles sont enregistrées, sans étape supplémentaire.

Pour lire la transcription actuelle d'un fichier par son identifiant de fichier d'espace de travail (le même texte que dans l'application), utilisez GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json avec la portée transcripts:read. Ses en-têtes X-Transcript-Version-Id et X-Transcript-Revision changent chaque fois que la transcription change ; un script qui interroge régulièrement sait ainsi quand il y a du nouveau. Les versions enregistrées sont sous GET /api/v1/jobs/JOB_ID/artifacts et GET /api/v1/artifacts/{artifact_id} ; une version enregistrée est un instantané figé qui n'inclut pas les modifications ultérieures.

Pour ne récupérer que les transcriptions qu'une personne a approuvées, demandez aux relecteurs d'appuyer sur « Marquer comme relu » dans l'éditeur. L'appel de transcription envoie alors X-Transcript-Review-Status: reviewed jusqu'à la modification suivante, et require_reviewed=true lui fait répondre 409 transcript_not_reviewed sinon. GET /api/v1/transcript-reviews?since=... liste les fichiers relus depuis votre dernière interrogation. Ou évitez les interrogations : ajoutez un webhook avec POST /api/v1/webhook-endpoints (portée webhooks:manage) pour transcript.reviewed, job.completed, job.failed, upload.completed ou upload.failed, et vérifiez l'en-tête KolWrite-Signature de chaque requête (HMAC-SHA256 de <t>.<raw body> avec le secret du point de terminaison).

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

6. Facultatif : la partager

Avec 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

Pour aller plus loin

Version Markdown de cette page