# 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 :

```bash
export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.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 :

```bash
# 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
```

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 :

```bash
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

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

```bash
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` :

```bash
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
```

## Pour aller plus loin

- [Authentification et scopes](/locales/fr/authentication.md)
- [Erreurs et limites de débit](/locales/fr/errors.md)
- [Référence complète de l’API](/) · [Spécification OpenAPI](/openapi.json)