Как получить временную метку для каждого слова в записи

Запрос

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

Отправьте запрос через POST /transcribe, а затем опрашивайте GET /transcribe/{jobId}, пока не придет статус COMPLETED. Указывайте параметр model явно: без него API запустит устаревшую модель core.

Ответ

{
  "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[] содержит время start и end в секундах, текст фрагмента text, метку speaker (если включена диаризация) и вложенный массив words[].
• В массиве words[] лежат объекты с полями start, end и word. Время указано в секундах и округлено до тысячных.
• Значения start и end у слова могут совпадать, а короткое слово порой длится сотые доли секунды. Не делите на длительность слова.
• Если передать в word_timestamps значение false или если сама модель размечает только целые реплики, массива words в ответе не будет. В этом случае вам доступны только границы фрагмента start и end.

Какие модели возвращают таймкоды слов

В обычном текстовом формате (txt) таймкодов нет. При генерации SRT через API этот параметр тоже учитывается, подробности есть в руководстве по SRT.

Поиск точного момента, где прозвучала фраза

Проводите поиск по «плоскому» списку слов и берите нужный временной отрезок. Тогда агент сможет ответить на вопрос «где она упоминает цены?» точным таймкодом или сразу вырезать эту фразу в отдельный клип.

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

Вырезаем клип по найденным границам:

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

Удаление пауз и склейка

Зная точное время каждого слова, легко вычислить тишину между ними. Мы можем оставить только плотную речь, а все паузы длиннее заданного порога вырезать:

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.

Полученные отрезки можно склеить функцией cut() из нашего руководства по видеомонтажу.

Где ещё пригодится пословная разметка

• Интерактивная подсветка текста в веб-плеере. Выделяйте в интерфейсе то слово, в границы которого попадает текущее время плеера currentTime.
• Навигация по записи через текст. Сделайте каждое слово ссылкой на ?t=<start>, чтобы по клику плеер перематывал запись на нужный момент.
• Разбивка на главы и хайлайты. Поручите LLM выбрать номера важных фрагментов, а ваш код подставит для них точное время.
• Поиск по медиатеке. Сохраняйте в базу слова вместе со временем их начала, чтобы из результатов поиска запись сразу открывалась на нужной секунде.
• Лингвистическая разметка и работа с корпусами. Таймкоды из нашего JSON легко перевести в форматы, с которыми работают ваши профильные программы.

Сколько это стоит

За временные метки слов доплачивать не нужно. Тарификация всегда посекундная и зависит только от выбранной модели: от 0,48 $ за час аудио на base и 1,44 $ за час на oracle. Все цены приведены в файле /llms/pricing.md.

Вопросы и ответы