# Come ottenere il timestamp di ogni parola da una registrazione

> Chiama POST /transcribe impostando output_format su json e word_timestamps su true (sono già i valori predefiniti). Nella risposta, ogni passaggio contiene un array words con oggetti {start, end, word} e i tempi in secondi. Qui vediamo com’è strutturato il risultato, quali modelli forniscono i tempi per parola e cosa puoi costruirci.

Ultimo aggiornamento: 2026-10-18 · HTML: https://console.kolwrite.com/it/guides/word-timestamps-api

## La richiesta

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

Avvia la trascrizione con `POST /transcribe` e interroga `GET /transcribe/{jobId}` finché lo stato non passa a `COMPLETED`. Specifica sempre il parametro `model`, altrimenti l’API userà di default il vecchio modello `core`.

## La risposta

```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[]`: contiene `start` ed `end` in secondi, `text`, `speaker` (se la diarizzazione è attiva) e l’array `words[]`.
- `words[]`: contiene `start`, `end` e `word`, con i tempi in secondi arrotondati al terzo decimale.
- Una parola molto breve può durare pochi centesimi di secondo, o persino avere lo stesso valore per `start` ed `end`. Evita quindi nel codice di dividere per la durata di una parola.
- Se imposti `word_timestamps` su `false`, oppure usi un modello che calcola i tempi solo per intero segmento, il campo `words` non sarà presente e avrai solo `start` ed `end` a livello di segmento.

## Quali modelli restituiscono i tempi per parola

| Modello | Tempi per parola |
| --- | --- |
| `base`, `oracle`, `oracle_pro`, `oracle_max` | Sì |
| `oracle_mini` | Tempi per segmento nella trascrizione standard; tempi per parola quando è attivo il riconoscimento degli interlocutori (diarizzazione o separazione dei canali) |
| `core`, `edge` (legacy) | Sì |

Il testo (`txt`) non ha tempi. L’SRT costruito dall’API segue lo stesso interruttore; vedi la [guida all’SRT](https://console.kolwrite.com/it/guides/srt-subtitles-api).

## Trovare il punto esatto in cui viene detta una frase

Se unisci tutte le parole in un unico elenco, puoi cercare un testo e ricavarne l’intervallo di tempo. È così che un agente può rispondere a «dove cita i prezzi?» indicando il momento esatto, o ritagliare quella frase per farne una 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
```

Estrarre un clip a partire da un intervallo di tempo:

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

## Accorciare le pause e creare jump cut

Conoscendo inizio e fine di ogni parola puoi calcolare la durata delle pause. Mantieni il parlato continuo e taglia i silenzi che superano una certa soglia:

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

Poi unisci gli intervalli usando la funzione `cut()` mostrata nella [guida al montaggio video](https://console.kolwrite.com/it/guides/video-editing-with-ai).

## Altri modi per usare i timestamp

- Testo sincronizzato in un player web: evidenzia via via la parola il cui intervallo contiene il valore `currentTime` del player.
- Trascrizioni interattive: trasforma ogni parola in un link che punta a `?t=<start>` per far saltare il player a quel punto.
- Capitoli e momenti chiave: fai scegliere a un LLM i numeri dei segmenti più rilevanti e usa il tuo codice per convertirli in timestamp.
- Ricerca in un archivio: salva nel database le parole insieme al loro tempo di inizio, così chi cerca un termine può aprire il file direttamente al secondo esatto.
- Allineamento e lavoro sui corpora: puoi convertire i tempi delle parole dal JSON nei formati di annotazione che i tuoi strumenti sanno leggere.

## Quanto costa

I timestamp per parola non comportano costi aggiuntivi. Paghi solo i secondi di audio elaborati in base al modello scelto, a partire da 0,48 US$ all’ora con `base` (un’ora con `oracle` costa 1,44 US$). Trovi il listino completo in [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Domande e risposte

### Come ottengo i timestamp per singola parola dall’API di trascrizione?

Passa nella richiesta `output_format: "json"` e `word_timestamps: true`. Ogni segmento della risposta includerà l’array `words[]` con i campi `start`, `end` e `word` espressi in secondi.

### Quali modelli supportano i timestamp per parola?

I modelli `base`, `oracle`, `oracle_pro` e `oracle_max` li restituiscono. `oracle_mini` fornisce i tempi dei passaggi, a meno che non sia attiva una modalità per gli interlocutori. L'output di testo non include invece i tempi.

### Quanto sono precisi i tempi delle parole?

KolWrite non pubblica metriche di precisione divise per lingua per questa API. I tempi sono pensati per evidenziare il testo a schermo e per tagliare l’audio tra una parola e l’altra; ti consigliamo comunque di fare una prova sulle tue registrazioni e di lasciare un piccolo margine attorno ai punti di taglio.

### Posso ottenere i timestamp da un file video?

Sì. L’API legge la traccia audio del video che invii. Per file oltre 100 MiB estrai prima l’audio con ffmpeg.

### I timestamp sono espressi in secondi o millisecondi?

In secondi, formattati come numeri con un massimo di tre cifre decimali (ad esempio `41.236`).

## Pagine correlate

- [Montare video con agenti IA](https://console.kolwrite.com/it/guides/video-editing-with-ai)
- [API per sottotitoli SRT](https://console.kolwrite.com/it/guides/srt-subtitles-api)
- [Sottotitoli per podcast e YouTube](https://console.kolwrite.com/it/guides/podcast-youtube-captions)
- [Linguistica e ricerca sulle lingue](https://console.kolwrite.com/it/use-cases/researchers)
- [Sviluppatori e team di prodotto](https://console.kolwrite.com/it/use-cases/developers)
- [Documentazione dell’API](https://console.kolwrite.com/it/public_api_docs)

---
Ottieni una chiave API: https://console.kolwrite.com/auth?lang=it · Documentazione dell’API: https://console.kolwrite.com/it/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt