# Como pegar o tempo exato de cada palavra em uma gravação

> Chame o endpoint POST /transcribe mantendo os padrões output_format como json e word_timestamps como true. Cada trecho do resultado traz uma lista words no formato {start, end, word}, com os tempos em segundos. Aqui você vai ver a estrutura dessa resposta, quais modelos retornam os tempos por palavra e o que dá para criar com isso.

Última atualização: 2026-10-18 · HTML: https://console.kolwrite.com/pt/guides/word-timestamps-api

## A requisição

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

Comece chamando `POST /transcribe` e consulte `GET /transcribe/{jobId}` até o status mudar para `COMPLETED`. Sempre passe o parâmetro `model`, porque sem ele a API usa o modelo legado `core`.

## A resposta

```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[]`: traz `start` e `end` em segundos, `text`, `words[]` e também `speaker` (se a diarização estiver ativa).
- `words[]`: contém `start`, `end` e `word`, com tempos em segundos arredondados em três casas decimais.
- Uma palavra curta pode durar poucos centésimos de segundo, e às vezes `start` e `end` vêm com o mesmo valor. Por isso, nunca faça divisões usando a duração de uma palavra no seu código.
- Se você passar `word_timestamps` como `false`, ou usar um modelo que só marca o tempo dos trechos, o campo `words` não vem na resposta. Você terá apenas o `start` e o `end` de cada trecho.

## Modelos que retornam o tempo por palavra

| Modelo | Tempos por palavra |
| --- | --- |
| `base`, `oracle`, `oracle_pro`, `oracle_max` | Sim |
| `oracle_mini` | Retorna tempos por trecho na transcrição simples, e tempos por palavra quando a diarização ou a separação de canais está ativa |
| `core`, `edge` (legados) | Sim |

O formato de texto puro (`txt`) não traz marcação de tempo. Já o SRT gerado pela API segue essa mesma regra de modelos; confira o [guia de SRT](https://console.kolwrite.com/pt/guides/srt-subtitles-api).

## Achar o momento exato de uma frase

Junte todas as palavras em uma lista única para buscar o termo e pegar o intervalo de tempo. Assim, um agente consegue responder perguntas como «onde ela menciona os preços?» apontando o segundo exato, ou já recortando esse trecho em um clipe.

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

Para gerar um clipe a partir de um intervalo de tempo:

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

## Cortar silêncios e fazer cortes secos

Com o tempo de cada palavra, você sabe exatamente o tamanho das pausas. Dá para manter a fala corrida e remover qualquer silêncio que passe de um limite:

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

Depois, junte os trechos usando a função `cut()` do nosso [guia de edição de vídeo](https://console.kolwrite.com/pt/guides/video-editing-with-ai).

## Outras formas de usar os tempos

- Destaque acompanhando o áudio no player web: basta grifar a palavra cujo intervalo inclui o `currentTime` atual.
- Transcrição clicável: transforme cada palavra em um link que leva o player para `?t=<start>`.
- Capítulos e momentos importantes: peça para um LLM escolher os números dos trechos e converta esses números em tempo no seu código.
- Busca em uma biblioteca: salve as palavras junto com o tempo de início para que o resultado da busca já abra no segundo certo.
- Alinhamento e trabalho com corpora: converta os tempos do JSON para o formato de anotação que as suas ferramentas usam.

## Quanto custa

Pedir o tempo por palavra não altera o preço. A cobrança é feita por segundo de áudio de acordo com a tabela do modelo escolhido, começando em US$ 0,48 por hora no `base`. No `oracle`, uma hora sai por US$ 1,44. Veja a tabela completa em [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Perguntas e respostas

### Como pego os carimbos de tempo por palavra na API de transcrição?

Passe `output_format: "json"` e `word_timestamps: true` na chamada. Cada trecho do resultado trará uma lista `words[]` com `start`, `end` e `word` em segundos.

### Quais modelos entregam o tempo por palavra?

Os modelos `base`, `oracle`, `oracle_pro` e `oracle_max` sempre entregam. O `oracle_mini` só retorna o tempo dos trechos, a menos que você ative algum modo de separação de falantes. Já a saída em texto puro não traz tempos.

### Qual é a precisão do tempo de cada palavra?

O KolWrite não divulga uma métrica de precisão por idioma para essa API. Na prática, a marcação funciona bem para destacar texto na tela e cortar áudio entre palavras. Vale testar com algumas gravações suas e deixar uma pequena margem de segurança nos pontos de corte.

### Consigo extrair os carimbos de tempo de um arquivo de vídeo?

Sim, a API lê a faixa de áudio direto do vídeo que você enviar. Se o arquivo passar de 100 MiB, extraia o áudio antes usando o ffmpeg.

### Os carimbos de tempo vêm em segundos ou milissegundos?

Vêm em segundos, formatados como números com até três casas decimais (como `41.236`).

## Páginas relacionadas

- [Editar vídeo com agentes de IA](https://console.kolwrite.com/pt/guides/video-editing-with-ai)
- [API de legendas SRT](https://console.kolwrite.com/pt/guides/srt-subtitles-api)
- [Legendas para podcasts e YouTube](https://console.kolwrite.com/pt/guides/podcast-youtube-captions)
- [Pesquisa linguística e de idiomas](https://console.kolwrite.com/pt/use-cases/researchers)
- [Desenvolvedores e times de produto](https://console.kolwrite.com/pt/use-cases/developers)
- [Documentação da API](https://console.kolwrite.com/pt/public_api_docs)

---
Obter uma chave de API: https://console.kolwrite.com/auth?lang=pt · Documentação da API: https://console.kolwrite.com/pt/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt