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

A requisição

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

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

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.

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

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

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

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

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.

Perguntas e respostas