# Comment obtenir l’horodatage de chaque mot d’un enregistrement

> Appelez POST /transcribe en laissant output_format à json et word_timestamps à true (les deux valeurs par défaut). Dans la réponse, chaque segment contient un tableau words d’objets {start, end, word} exprimés en secondes. Ce guide détaille le format renvoyé, les modèles compatibles et des exemples d’utilisation.

Dernière mise à jour: 2026-10-18 · HTML: https://console.kolwrite.com/fr/guides/word-timestamps-api

## La requête

```json
{
  "audio_url": "https://example.com/interview.mp3",
  "model": "oracle",
  "language": "auto",
  "word_timestamps": true,
  "output_format": "json"
}
```

Lancez la tâche avec `POST /transcribe`, puis interrogez `GET /transcribe/{jobId}` jusqu’au statut `COMPLETED`. Pensez à toujours préciser `model` : sans ce paramètre, l’API se rabat sur l’ancien modèle `core`.

## La réponse

```json
{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 1.0,
        "end": 3.75,
        "text": "Hello everyone and welcome to the show.",
        "speaker": "Speaker 1",
        "words": [
          { "start": 1.0, "end": 1.35, "word": "Hello" },
          { "start": 1.4, "end": 1.75, "word": "everyone" }
        ]
      }
    ]
  }
}
```

- `segments[]` : contient `start` et `end` (en secondes), `text`, `speaker` (si la diarisation est activée) et le tableau `words[]`.
- `words[]` : contient `start`, `end` et `word`, avec des temps en secondes arrondis à trois décimales.
- Il arrive qu’un mot ait la même valeur pour `start` et `end`, ou qu’un mot très court ne dure que quelques centièmes de seconde. Évitez donc de diviser par la durée d’un mot dans vos calculs.
- Si vous passez `word_timestamps` à `false`, ou si le modèle choisi ne fournit l’horodatage que par segment, le champ `words` est omis. Vous conservez toutefois le `start` et le `end` de chaque segment.

## Quels modèles fournissent l’horodatage mot à mot

| Modèle | Horodatage par mot |
| --- | --- |
| `base`, `oracle`, `oracle_pro`, `oracle_max` | Oui |
| `oracle_mini` | Horodatage par segment en transcription simple ; horodatage par mot dès qu’un mode locuteurs (diarisation ou séparation de canaux) est activé |
| `core`, `edge` (anciens modèles) | Oui |

La sortie texte brut (`txt`) ne contient aucun horodatage. Les fichiers SRT générés par l’API suivent la même logique ; consultez à ce sujet le [guide SRT](https://console.kolwrite.com/fr/guides/srt-subtitles-api).

## Repérer le moment exact où une phrase est prononcée

Aplatissez la liste des mots pour y lancer votre recherche et récupérer l’intervalle de temps correspondant. Votre agent pourra ainsi répondre à « où parle-t-elle des tarifs ? » en donnant l’instant exact, ou découper directement ce passage en clip.

find.py

```python
# find.py — where is a phrase said? Returns (start, end) in seconds.
import re


def find_phrase(result, phrase):
    words = [w for segment in result["segments"] for w in segment.get("words", [])]
    clean = lambda text: re.sub(r"[^\w]", "", text.lower())
    target = [clean(p) for p in phrase.split()]
    tokens = [clean(w["word"]) for w in words]
    for i in range(len(tokens) - len(target) + 1):
        if tokens[i:i + len(target)] == target:
            return words[i]["start"], words[i + len(target) - 1]["end"]
    return None


# start, end = find_phrase(result, "welcome to the show")
# ffmpeg -ss <start> -to <end> -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

Extraire un clip à partir d’une plage de temps :

```bash
ffmpeg -ss 41.2 -to 47.8 -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

## Raccourcir les silences et monter à la coupe

Avec les mots, vous connaissez aussi l’écart qui les sépare. Vous pouvez ainsi conserver la parole continue et couper les pauses qui dépassent un certain seuil :

silences.py

```python
# silences.py — keep the speech, drop pauses longer than max_gap seconds
def speech_ranges(words, max_gap=0.7, pad=0.1):
    ranges = []
    for word in words:
        if ranges and word["start"] - ranges[-1][1] <= max_gap:
            ranges[-1][1] = word["end"]
        else:
            ranges.append([word["start"], word["end"]])
    return [[max(0.0, s - pad), e + pad] for s, e in ranges]

# Pass the ranges to cut() from cut.py to build the tightened video.
```

Assemblez ensuite les plages retenues à l’aide de la fonction `cut()` présentée dans le [guide du montage vidéo](https://console.kolwrite.com/fr/guides/video-editing-with-ai).

## Autres cas d’usage de l’horodatage mot à mot

- Suivi façon karaoké dans un lecteur web : mettez en évidence le mot dont la plage encadre `currentTime`.
- Transcriptions interactives : rendez chaque mot cliquable avec un lien vers `?t=<start>` pour caler le lecteur à cet endroit.
- Chapitrage et moments forts : laissez un LLM sélectionner les numéros de segments pertinents, puis traduisez-les en codes temporels dans votre code.
- Recherche dans une bibliothèque : enregistrez chaque mot avec son temps de début pour ouvrir les résultats de recherche à la seconde près.
- Alignement et travail sur corpus : convertissez les repères temporels des mots du JSON vers les formats d’annotation que lisent vos outils.

## Combien ça coûte

L’horodatage mot à mot n’entraîne aucun surcoût. La facturation se fait à la seconde d’audio selon le modèle choisi, à partir de 0,48 US$ par heure avec `base` (et 1,44 US$ par heure avec `oracle`). Consultez la grille complète sur [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Questions et réponses

### Comment obtenir l’horodatage mot à mot avec une API de transcription ?

Passez `output_format: "json"` et `word_timestamps: true` dans votre requête. Chaque segment renvoyé contiendra un tableau `words[]` indiquant `start`, `end` et `word` en secondes.

### Quels modèles prennent en charge l’horodatage par mot ?

Les modèles `base`, `oracle`, `oracle_pro` et `oracle_max` le fournissent systématiquement. `oracle_mini` ne renvoie que les temps par segment, sauf si un mode d’identification des locuteurs est activé. Enfin, la sortie texte brut ne comporte aucun horodatage.

### Quelle est la précision de l’horodatage des mots ?

KolWrite ne publie pas de chiffre de précision par langue pour cette API. En pratique, le calage des mots est assez fin pour la surbrillance ou pour couper entre deux mots. Faites un essai sur quelques-uns de vos enregistrements et gardez une petite marge autour de vos points de coupe.

### Peut-on récupérer l’horodatage à partir d’un fichier vidéo ?

Oui. L’API lit directement la piste audio de la vidéo que vous envoyez. Si le fichier dépasse 100 MiB, extrayez d’abord l’audio avec ffmpeg.

### Les temps sont-ils exprimés en secondes ou en millisecondes ?

En secondes, sous forme de nombres comptant jusqu’à trois décimales (par exemple `41.236`).

## Pages associées

- [Monter une vidéo avec des agents IA](https://console.kolwrite.com/fr/guides/video-editing-with-ai)
- [API de sous-titres SRT](https://console.kolwrite.com/fr/guides/srt-subtitles-api)
- [Sous-titres pour podcasts et YouTube](https://console.kolwrite.com/fr/guides/podcast-youtube-captions)
- [Recherche linguistique](https://console.kolwrite.com/fr/use-cases/researchers)
- [Développeurs et équipes produit](https://console.kolwrite.com/fr/use-cases/developers)
- [Documentation de l’API](https://console.kolwrite.com/fr/public_api_docs)

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