Documentation de l’API KolWrite

Authentification

Toutes les requêtes d’API doivent être authentifiées avec votre clé d’API unique. Incluez-la dans les en-têtes de la requête :

x-api-key: YOUR_API_KEY

Vous pouvez générer et gérer vos clés d’API dans la section Console KolWrite après avoir créé un compte.

Démarrage rapide

Démarrez rapidement grâce à ces exemples de base.

1. Lancez la transcription

Envoyez une requête POST au point de terminaison `/transcribe` avec l’URL du fichier audio à transcrire.

Requête :

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Réponse :

L’API renvoie un `jobId` qui vous permettra de récupérer les résultats de la transcription.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Récupérez le résultat de la transcription

Du Send a GET request au the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Requête :

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Réponse (exemple) :

Une fois que le statut de la tâche est COMPLETED, la réponse inclura les détails de la transcription.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Modèles et crédits d’utilisation

L’utilisation des modèles est décomptée en crédits d’utilisation à la seconde, sans facturation minimale. Le paiement, les reçus et les documents fiscaux indiquent la devise réellement utilisée pour l’achat.

1 crédit est l’unité de facturation de l’API, précédemment affichée comme $1.00 dans la console API.

Les comptes de facturation israéliens admissibles achètent des crédits d’utilisation en ILS au prix net de ILS 3.60 par crédit avant TVA. Avant le paiement, le récapitulatif indique les crédits d’utilisation, le montant net, la TVA et le total final en ILS. Les autres comptes achètent des crédits d’utilisation en USD au prix de USD 1.20 par crédit, sauf conditions de commande distinctes.

Options : La diarisation standard des locuteurs et le mode standard de séparation des canaux sont inclus. La diarisation Pro des locuteurs ajoute 0.20 crédit par heure audio. overlap la séparation des canaux est facturée au tarif du modèle sélectionné pour la plus grande valeur entre la durée de l’enregistrement et le temps de parole total détecté sur ses canaux physiques ; aucun mode de canal n’ajoute de supplément de diarisation. Oracle Mini active automatiquement l’alignement des horodatages lorsque la diarisation des locuteurs ou la séparation des canaux est sélectionnée.

Points de terminaison de l’API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Envoie un fichier audio pour une transcription asynchrone avec diarisation facultative des locuteurs.

Paramètres du corps de la requête

Exemple de requête (avec diarisation) :

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Réponse :

Renvoie un objet contenant le `jobId` de la tâche de transcription envoyée.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Récupère le statut et le résultat d’une tâche de transcription donnée.

Paramètres de chemin

Corps de la réponse

Exemple de réponse (sortie JSON avec diarisation des locuteurs) :

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Diarisation des locuteurs

La diarisation des locuteurs consiste à identifier et à séparer les différents locuteurs d’un enregistrement audio. Lorsqu’elle est activée, KolWrite analyse l’audio afin de détecter les changements de locuteur et d’étiqueter chaque segment en conséquence.

La diarisation des locuteurs et la séparation des canaux sont disponibles avec tous les modèles répertoriés. Oracle Mini active automatiquement l’alignement des horodatages chaque fois qu’un mode de locuteur est sélectionné.

Activer la diarisation

Pour activer la diarisation des locuteurs, définissez le paramètre include_diarization sur la valeur true dans votre requête de transcription :

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Optimisation du nombre de locuteurs

Pour de meilleurs résultats, indiquez le nombre attendu de locuteurs à l’aide du paramètre num_speakers . Si vous ne connaissez pas le nombre exact, vous pouvez :

• Omettre le paramètre (le système effectuera une détection automatique)
• Indiquer une estimation en saisissant votre meilleure approximation

Diarisation Pro

Pour identifier les locuteurs avec davantage de précision, notamment lorsque l’acoustique est difficile, vous pouvez activer la diarisation Pro. Cette fonctionnalité coûte un supplément de 0.20 crédit par heure audio.

Pour l’utiliser, définissez le paramètre pro_diarization sur la valeur true. Ce paramètre peut être utilisé avec include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Séparation des locuteurs par canal

La séparation des canaux transcrit chaque piste audio physique séparément et étiquette les segments et les mots renvoyés avec leurs champs physiques channel et speaker. Elle nécessite une source à deux à huit canaux indiquée par audio_url et ne peut pas être combinée avec la diarisation standard ou Pro. Oracle Mini active automatiquement l’alignement des horodatages pour l’un ou l’autre mode de canal.

Utiliser standard lorsque les locuteurs parlent à tour de rôle ; un seul tarif audio du modèle sélectionné est facturé. Utilisez overlap lorsque les prises de parole peuvent se chevaucher ; le tarif du modèle sélectionné est facturé pour la plus grande valeur entre la durée de l’enregistrement et le temps de parole total détecté sur ses canaux physiques.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhooks de fin de traitement

Définissez webhook_url pour recevoir les événements transcription.completed et transcription.failed . En cas d’échec, la livraison est retentée, mais les clients doivent continuer à prendre en charge GET /transcribe/{jobId} comme source de référence.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Chaque livraison inclut X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id et X-KolWrite-Timestamp. Chaque événement est livré au moins une fois ; les nouvelles tentatives réutilisent le même ID de livraison. Dédupliquez donc les événements à l’aide de X-KolWrite-Delivery-Id. Lorsqu’un secret est configuré, calculez le HMAC-SHA256 sur timestamp + "." + raw_request_body et comparez-le à X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

Pour output_format: "json", dans le webhook, le champ result est un objet JSON. Les résultats TXT et SRT sont fournis sous forme de chaînes de caractères.

Pour les résultats volumineux, le paramètre result_omitted peut prendre la valeur true; récupérez le résultat complet depuis GET /transcribe/{jobId}. Les événements en échec comprennent un champ error champ.

Format de sortie avec diarisation

Lorsque la diarisation est activée, chaque segment de la sortie JSON inclut un champ speaker qui identifie le locuteur (p. ex. « Speaker 1 », « Speaker 2 », etc.).

Formats de sortie

Format JSON

Sortie détaillée comprenant les segments, les horodatages et, en option, les données au niveau des mots.

Format TXT

Transcription en texte brut avec libellés des locuteurs (lorsque la diarisation est activée).

Format SRT

Format de sous-titres SubRip avec horodatages, compatible avec les lecteurs vidéo et les éditeurs de sous-titres.

État du service

Consultez la page d’état de l’API KolWrite pour consulter la disponibilité en direct, l’historique de disponibilité et les incidents liés au niveau de service.

GET /health ne nécessite aucune clé API et renvoie l’état actuel de l’API, de la réception des tâches et du traitement des transcriptions. Une réponse 200 signifie que le service est opérationnel ou dégradé ; une réponse 503 signifie que l’état actuel est inconnu ou indisponible. Les deux réponses contiennent des détails d’état au format JSON.

GET /health/history?period=24h renvoie un historique compact de disponibilité. Les périodes prises en charge sont 24h, 7d et 30d.

Codes de statut