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.kolwrite.com
1. Créer un token
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.kolwrite.com/api/v1/billing/balance2. 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.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_idLes 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.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.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting5. Exporter la transcription
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
"https://api.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"Formats : text, json, srt, vtt. Les artefacts de transcription persistants, avec historique des versions, sont disponibles via GET /api/v1/jobs/JOB_ID/artifacts et GET /api/v1/artifacts/{artifact_id} avec le scope transcripts:read.
Le téléchargement des SRT et VTT nécessite l’offre Plus ou supérieure ; les autres offres reçoivent un HTTP 403 avec le code subtitle_export_requires_plus.
6. Facultatif : la partager
Avec 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