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

> Отправьте запрос POST /transcribe с параметрами output_format со значением json и word_timestamps со значением true (оба включены по умолчанию). Внутри каждого фрагмента вернётся массив words с объектами {start, end, word}, где время указано в секундах. Ниже разберём формат ответа, поддерживаемые модели и практические задачи, которые можно решить с помощью этих меток.

Обновлено: 2026-10-18 · HTML: https://console.kolwrite.com/ru/guides/word-timestamps-api

## Запрос

```json
{
  "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`.

## Ответ

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

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

| Модель | Времена слов |
| --- | --- |
| `base`, `oracle`, `oracle_pro`, `oracle_max` | Да |
| `oracle_mini` | При обычной расшифровке возвращает только границы фрагментов, а при включении диаризации или разделения каналов добавляет и времена отдельных слов |
| `core`, `edge` (устаревшие) | Да |

В обычном текстовом формате (`txt`) таймкодов нет. При генерации SRT через API этот параметр тоже учитывается, подробности есть в [руководстве по SRT](https://console.kolwrite.com/ru/guides/srt-subtitles-api).

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

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

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

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

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

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

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

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

Полученные отрезки можно склеить функцией `cut()` из нашего [руководства по видеомонтажу](https://console.kolwrite.com/ru/guides/video-editing-with-ai).

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

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

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

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

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

### Как получить временные метки для каждого слова через API расшифровки?

Передайте в запросе `output_format: "json"` и `word_timestamps: true`. Внутри каждого фрагмента придёт массив `words[]`, где для каждого слова указаны `start`, `end` (в секундах) и само слово `word`.

### Какие модели поддерживают пословные метки времени?

Времена слов всегда возвращают модели `base`, `oracle`, `oracle_pro` и `oracle_max`. Модель `oracle_mini` по умолчанию отдаёт только границы целых фрагментов, но если включить определение говорящих, появятся и слова. В простом текстовом формате таймкодов не бывает.

### Насколько точны эти таймкоды?

KolWrite не публикует отдельные метрики точности таймкодов по языкам. На практике этой точности хватает для синхронной подсветки текста и монтажа по паузам между словами. Советуем протестировать API на своих записях и при нарезке оставлять небольшой запас по краям.

### Можно ли получить временные метки для видеофайла?

Да, API сам прочитает звуковую дорожку из загруженного видео. Но если файл весит больше 100 MiB, предварительно извлеките из него аудио через ffmpeg.

### Время возвращается в секундах или миллисекундах?

В секундах, в виде десятичной дроби с точностью до трёх знаков после запятой (например, `41.236`).

## Связанные страницы

- [Монтаж видео с ИИ-агентами](https://console.kolwrite.com/ru/guides/video-editing-with-ai)
- [API для создания субтитров SRT](https://console.kolwrite.com/ru/guides/srt-subtitles-api)
- [Субтитры для подкастов и YouTube](https://console.kolwrite.com/ru/guides/podcast-youtube-captions)
- [Лингвистика и языковые исследования](https://console.kolwrite.com/ru/use-cases/researchers)
- [Разработчики и продуктовые команды](https://console.kolwrite.com/ru/use-cases/developers)
- [Документация API](https://console.kolwrite.com/ru/public_api_docs)

---
Получить ключ API: https://console.kolwrite.com/auth?lang=ru · Документация API: https://console.kolwrite.com/ru/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt