# Transcription pour apps et produits SaaS

> Ajoutez notes vocales, comptes rendus de réunion, sous-titres ou audio consultable à votre produit avec une API REST asynchrone : envoyer, lancer une tâche, recevoir le webhook, stocker les segments.

Dernière mise à jour: 2026-10-08 · HTML: https://console.kolwrite.com/fr/use-cases/developers

## Le flux en production

1. Votre backend appelle `POST /upload` pour le fichier de l’utilisateur et renvoie le formulaire signé au client, ou l’envoie lui-même (jusqu’à 100 Mio).
2. Lancez la tâche avec le `fileUrl` renvoyé comme `audio_url` et votre `webhook_url`.
3. Vérifiez la signature du webhook, dédoublonnez sur `X-KolWrite-Delivery-Id`, puis appelez `GET /transcribe/{jobId}` si `result_omitted` vaut true.
4. Stockez les `segments` (texte, temps, locuteurs) et affichez-les ; exportez `srt` ou `txt` à la demande.

Requête de la tâche :

```json
{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}
```

## Vérifier les webhooks

```javascript
import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

Les livraisons arrivent au moins une fois et sont relancées en cas d’échec. `GET /transcribe/{jobId}` reste la source de vérité.

## Choisir le modèle à chaque tâche

| Besoin produit | Réglage | Pourquoi |
| --- | --- | --- |
| Audio propre, gros volume, petit coût | `model: "base"` | 0,40 crédit (0,48 US$) par heure |
| Par défaut pour les fichiers des utilisateurs | `model: "oracle"` | Qualité production, traduction possible |
| Transcription dans une autre langue | Modèle Oracle + `translate_to` | Une tâche, texte traduit |
| Qui a dit quoi | `include_diarization: true` | Inclus dans le prix |
| Sous-titres | `output_format: "srt"` | Prêt pour les lecteurs vidéo |

## Limites à prévoir

- Envoi Base64 en ligne : 4 Mio de média décodé. Envoi signé : 100 Mio.
- Le formulaire signé expire après 60 minutes ; l’URL de lecture après 24 heures.
- Les tâches sont asynchrones : affichez la progression avec `PENDING` et `IN_PROGRESS`.
- `channel_speaker_separation` ne se combine pas avec la diarisation.

## Questions et réponses

### Existe-t-il un SDK ?

L’API est en HTTPS et JSON simples ; n’importe quel client HTTP convient. Le fichier OpenAPI 3.1 sur /openapi.json fonctionne avec les générateurs de code.

### Comment éviter de traiter deux fois un webhook ?

Dédoublonnez sur `X-KolWrite-Delivery-Id` ; les nouvelles tentatives réutilisent cet identifiant.

### Comment l’usage est-il facturé ?

À la seconde d’audio, au tarif en crédits du modèle, sans minimum. 1 crédit vaut 1,20 US$.

## Pages associées

- [Agents IA et vibe coding](https://console.kolwrite.com/fr/use-cases/ai-agents)
- [Centres d’appels et ventes](https://console.kolwrite.com/fr/use-cases/call-centers)
- [Entreprises](https://console.kolwrite.com/fr/use-cases/enterprise)
- [Langues prises en charge](https://console.kolwrite.com/fr/languages/)

---
Obtenir une clé API: https://console.kolwrite.com/auth?lang=fr · Documentation de l’API: https://console.kolwrite.com/fr/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt