remotion_service/docs/consults/api-services-research_2026-04.md

# Исследование API-сервисов: Video Intelligence, STT, TTS & B-Roll

**Дата:** 1 апреля 2026
**Консультанты:** ML/AI-инженер, Backend-архитектор, Remotion-инженер, Product Lead, + 4 исследовательских агента
**Контекст:** Глубокий анализ API-сервисов для будущих фич — highlight detection, shorts generation, semantic search, B-Roll

---

## Содержание

1. [Executive Summary](#1-executive-summary)
2. [STT — обновлённое сравнение](#2-stt--обновлённое-сравнение)
3. [TTS — обновлённое сравнение](#3-tts--обновлённое-сравнение)
4. [Video Intelligence — полное сравнение](#4-video-intelligence--полное-сравнение)
5. [TwelveLabs — глубокий анализ](#5-twelvelabs--глубокий-анализ)
6. [Gemini 2.5 — ключевой новый игрок](#6-gemini-25--ключевой-новый-игрок)
7. [Clipping-платформы (OpusClip, Reap, Vizard)](#7-clipping-платформы)
8. [B-Roll генерация](#8-b-roll-генерация)
9. [Архитектура интеграции в Coffee Project](#9-архитектура-интеграции-в-coffee-project)
10. [Remotion Pipeline — эволюция](#10-remotion-pipeline--эволюция)
11. [Продуктовая стратегия и монетизация](#11-продуктовая-стратегия-и-монетизация)
12. [Сводная таблица стоимости](#12-сводная-таблица-стоимости)
13. [Рекомендации и дорожная карта](#13-рекомендации-и-дорожная-карта)
14. [Красные флаги в текущем коде](#14-красные-флаги-в-текущем-коде)
15. [Источники](#15-источники)

---

## 1. Executive Summary

### Ключевые находки

1. **Gemini 2.5 Flash — game-changer.** $0.005/мин за видеоанализ (20-60x дешевле TwelveLabs). Достаточно для MVP highlight detection.

2. **TwelveLabs оправдан только для повторных запросов.** Модель «проиндексируй раз — ищи многократно» выгодна при 10+ запросах к одному видео. Для одноразового анализа — Gemini дешевле.

3. **ElevenLabs Scribe v2 — лучший STT для нашего продукта.** WER 2.3%, точные пословные таймстемпы (критично для субтитров), встроенная диаризация. $0.40/час.

4. **B-Roll генерация НЕ готова для продакшна.** Рекомендация: Pexels API (бесплатный) для поиска стокового видео по ключевым словам из транскрипции.

5. **Reap.video — неожиданно сильный конкурент.** API + CLI + MCP за $9.99/мес, 98 языков для субтитров. Дешевле и доступнее OpusClip.

6. **У Coffee Project нулевая инфраструктура монетизации.** Нет планов, тарифов, трекинга использования, биллинга. Это блокер для любых платных фич.

7. **Русский рынок — first-mover advantage.** Нет локальных конкурентов в AI video clipping. Западные инструменты недоступны из-за санкций.

### Рекомендуемый стек (обновлённый)

| Задача | Сервис | Цена | Зачем именно этот |
|--------|--------|------|-------------------|
| STT (продакшн) | ElevenLabs Scribe v2 | $0.40/час | Лучший WER + таймстемпы для субтитров |
| STT (черновик/preview) | Whisper v3-turbo (DeepInfra) | $0.06/час | 253x realtime, мгновенный preview |
| Highlight detection (MVP) | Gemini 2.5 Flash | $0.005/мин | 20-60x дешевле TwelveLabs |
| Highlight detection (premium) | TwelveLabs Pegasus 1.2 | $0.063/мин | Лучшая точность для автоматизации |
| Chapters | Gemini 2.5 Flash | $0.005/мин | Достаточно качества, минимальная цена |
| Semantic search | TwelveLabs Marengo 3.0 | $4/1000 запросов | Единственный с pre-indexed search |
| B-Roll suggestions | Pexels API | Бесплатно | Реальное видео > AI-генерация |
| TTS (русский) | SaluteSpeech | $2.1/1M символов | Самый дешёвый для RU |

---

## 2. STT — обновлённое сравнение

### Сравнительная таблица (апрель 2026)

| Сервис | WER (EN) | WER (RU, оценка) | $/час | Пословные таймстемпы | Диаризация | Особенности |
|--------|----------|-------------------|-------|----------------------|------------|-------------|
| **ElevenLabs Scribe v2** | **2.3%** | ~5-7% | $0.40 | Да, точные (для субтитров) | Да (batch) | Audio tagging (смех, музыка), 90+ языков |
| **Deepgram Nova-3 Mono** | 5.4% | ~8-12% | $0.46 | Да, улучшены в v3 | Да (+$0.12/час) | Code-switching 10 языков в одном потоке |
| **Deepgram Nova-3 Multi** | 5.4% | ~8-12% | $0.55 | Да | Да | Мультиязычная версия |
| **Whisper large-v3 (stock)** | 4.2% | 9.0% | $0.06 (DeepInfra) | Да, ±500ms нативно | Нет | Open-source, pay-as-you-go |
| **Whisper large-v3 (fine-tuned RU)** | — | **6.4%** | Self-hosted | Да, ±500ms | Нет | Требует GPU, инфраструктура |
| **Whisper v3-turbo** | 4.8% | 10.2% | $0.06 (DeepInfra) | Да, менее точные | Нет | 253x realtime, 6x быстрее large |
| **Google Speech V1** (текущий) | ~6-8% | ~8-12% | ~$0.06/15сек | Да | Да | Уже интегрирован |

### Критический вывод: точность таймстемпов

Для Coffee Project **точность пословных таймстемпов — главная метрика**, потому что субтитры синхронизируются покадрово в Remotion через `WordNode.time.start/end`.

- **ElevenLabs Scribe v2**: создан для субтитрирования. Точность таймстемпов достаточна без постобработки.
- **Whisper нативный**: ±500ms на уровне сегментов. Пословные таймстемпы из cross-attention весов — заметно неточные. Это проблема, которая уже есть в проекте.
- **Whisper + WhisperX**: значительно лучше через wav2vec2 forced alignment, но добавляет вторую модель и сложность.

### Рекомендация ML/AI-инженера

**Двухуровневая архитектура STT:**

| Уровень | Движок | Задержка | $/час | Когда |
|---------|--------|----------|-------|-------|
| Черновик (мгновенный) | Whisper v3-turbo (DeepInfra) | ~2-3 сек на 5 мин | $0.06 | Preview сразу после загрузки |
| Продакшн (точный) | ElevenLabs Scribe v2 | ~15-30 сек на 5 мин | $0.40 | Заменяет черновик, используется для рендера |

Экономия: 85% на большинстве взаимодействий (просмотр, предпросмотр), где достаточно черновика.

### Новое в ElevenLabs Scribe v2

- **Audio tagging** (январь 2026): детектирует смех, аплодисменты, музыку, шаги, фоновый шум. Теги появляются inline в транскрипте с таймстемпами: `(laughter)`, `(music)`.
- **Scribe v2 Realtime**: 30-80ms задержка, 93.5% точность на 30 языках.
- **Voice Isolator**: нейронное разделение речи — полезно для предобработки шумного видео.

### Новое в Deepgram Nova-3

- **54.2% снижение WER** для стриминга vs конкурентов.
- **Live code-switching**: 10 языков (включая русский) в одном потоке.
- **Keyterm prompting**: мультиязычный, улучшает точность для специфических терминов.
- **Audio Intelligence — по-прежнему только EN.** Sentiment, topics, intent — только английский. Это критическое ограничение для нашего продукта.

---

## 3. TTS — обновлённое сравнение

Без изменений vs первоначальное исследование. Обновлённые цены Deepgram:

| Сервис | $/1K символов | $/1M символов | Особенности |
|--------|---------------|---------------|-------------|
| **SaluteSpeech** (Сбер) | ~$0.0021 | ~$2.1 | Самый дешёвый. RU/EN/KZ |
| **Deepgram Aura-1** | $0.015 | $15 | Предыдущее поколение |
| **Deepgram Aura-2** | $0.030 | $30 | Новейшая модель |
| **ElevenLabs Flash/Turbo** | $0.06 | $60 | Business tier, ~75ms, 32 языка |
| **ElevenLabs Multilingual v2/v3** | $0.12 | $120 | Премиум качество, voice cloning |

---

## 4. Video Intelligence — полное сравнение

### Сравнительная матрица

| Параметр | TwelveLabs | Gemini 2.5 Pro | Gemini 2.5 Flash | GPT-4o/4.1 | Google Video Intelligence | Azure Video Indexer |
|----------|-----------|----------------|------------------|------------|--------------------------|---------------------|
| **Тип** | Video-native foundation models | General VLM с видеовходом | General VLM (лёгкий) | Image-only (кадры) | Structured annotation | ML pipeline orchestrator |
| **Архитектура** | Marengo (embeddings) + Pegasus (генерация) | Мультимодальный LLM | Мультимодальный LLM | Мультимодальный LLM (без видео) | Отдельные ML-модели | Набор Azure AI сервисов |
| **Highlight detection** | Нативный API, таймкоды | Через промпт, секундные таймкоды | Через промпт | Нет | Нет | Нет |
| **Semantic search** | Pre-indexed (Marengo) | Промпт-based | Промпт-based | Нет | Нет | Нет |
| **Chapters** | Нативный API | Через промпт | Через промпт | Через промпт | Нет | Нет |
| **Object tracking** | Сильный, cross-frame | Ограниченный | Ограниченный | Нет (между кадрами) | Отдельная фича ($0.15/мин) | Да |
| **Макс. длительность** | 4 часа (Marengo), 1 час (Pegasus) | ~6 часов (2M контекст) | ~6 часов | Ограничен кадрами | Без лимита | 12 часов (free tier) |
| **Русская речь** | Да (36+ языков) | Да (сильный) | Да | Нет нативного аудио | 50+ языков | 50+ языков |
| **Цена за 1 мин** | $0.063 (index+analyze) | $0.021 (≤200k) | **$0.005** | $0.026-0.23 | $0.025-0.15 (per feature) | Custom |
| **Цена за 1 час** | $3.78 | $1.26 | **$0.36** | $1.56-13.80 | $1.50-9.00 | Custom |
| **Повторные запросы** | $4/1000 (дёшево) | Пересчитываются (дорого) | Пересчитываются | Пересчитываются | — | — |
| **Бенчмарки** | SOTA VideoMME-Long (30+ мин) | 85.2% VideoMME | Ниже Pro | 72% VideoMME | — | — |

### Ключевой инсайт: «проиндексируй раз — ищи многократно»

TwelveLabs заявляет ~36,000x дешевле Gemini для повторных запросов к тому же видео ($0.09/видео-час/месяц vs $4.50/1M токенов за запрос). Но для **одноразового анализа** (highlight detection для одного видео) — Gemini 2.5 Flash в 12x дешевле.

---

## 5. TwelveLabs — глубокий анализ

### Актуальные модели (апрель 2026)

| Модель | Статус | Назначение | Ключевые улучшения |
|--------|--------|-----------|-------------------|
| **Marengo 3.0** | GA (текущая) | Embeddings, Search | 512-dim (было 1024), composed text+image search, спорт, 36 языков, 4 часа видео, 2x быстрее |
| **Pegasus 1.2** | GA (текущая) | Analyze, генерация | 1 час видео, меньше галлюцинаций, SOTA на VideoMME-Long |
| Marengo 2.7 | **Sunset 30 марта 2026** | — | Устарела |
| Pegasus 1.1 | **Discontinued** | — | Автообновлена до 1.2 |

### Подтверждённые цены (Developer plan)

| Компонент | Цена | Подтверждено |
|-----------|------|-------------|
| Video indexing (Marengo/Pegasus) | $0.042/мин ($2.52/час) | ✅ |
| Infrastructure (хранение индексов) | $0.0015/мин ($0.09/час/мес) | ✅ |
| Analyze API input (Pegasus) | $0.021/мин | ✅ |
| Analyze API output | $7.50/1M токенов | ✅ |
| Search API | $4/1000 запросов | ✅ |
| Embed API (video) | $0.042/мин | ✅ |
| **Embed API (audio only)** | **$0.0083/мин** | 🆕 |
| **Embed API (image)** | **$0.10/1000 запросов** | 🆕 |
| **Embed API (text)** | **$0.07/1000 запросов** | 🆕 |

Free tier: 600 минут, 100 видео, 90 дней хранения.

### SDK и интеграция

**Python SDK** (`pip install twelvelabs`, v1.2.1):
```python
from twelvelabs import TwelveLabs
client = TwelveLabs(api_key=API_KEY)

# Highlight detection
res = client.generate.summarize(video_id="...", type="highlight")
for hl in res.highlights:
    print(f"{hl.start}s-{hl.end}s: {hl.highlight}")

# Chapter generation
res = client.generate.summarize(video_id="...", type="chapter")
for ch in res.chapters:
    print(f"{ch.start}s-{ch.end}s: {ch.chapter_title}")

# Structured JSON output (новое)
result = client.analyze(
    video_id="...",
    prompt="Extract key moments",
    response_format=ResponseFormat(type="json_schema", json_schema={...})
)
```

**Node.js SDK**: `npm install twelvelabs-js` (production-ready).

**OpenAPI spec**: 8,400 строк, доступен в [repo](https://github.com/twelvelabs-io/twelvelabs-developer-experience).

### Ограничения и gotchas

- Текстовый запрос: макс **77 токенов** (Marengo), **500 токенов** (Marengo 3.0)
- Промпт Pegasus: макс **375 токенов**
- Видео: 360x360 — 5184x2160, aspect ratio 1:1 — 2.4:1, мин 4 сек
- Размер файла: макс 200 МБ (прямая загрузка), 4 ГБ (multipart/URL)
- Индексация: только async, нужно poll status или webhook
- **Webhooks только для индексации** — нет для analyze/search/embed
- Rate limits: Free 8 RPM, Dev Tier 1 = 600 RPM (search), автоапгрейд при $200+/мес

### Интеграции из repo

- **Vector Store RAG**: ChromaDB, Weaviate, LanceDB, Oracle
- **Real-time мониторинг**: VideoDB (RTSP feeds)
- **Visual pipelines**: Langflow
- **Chatbot**: Poe

---

## 6. Gemini 2.5 — ключевой новый игрок

### Почему это важно

Gemini 2.5 Flash при $0.005/мин — это **20-60x дешевле TwelveLabs** для одноразового видеоанализа. С 2M-токенным контекстом может обработать ~6 часов видео за один вызов. Это делает highlight detection доступным даже на free tier нашего продукта.

### Pricing per minute video

Видео потребляет **258 токенов/сек** (1 fps). Аудио добавляет **25 токенов/сек**.

| Модель | $/мин (видео) | $/мин (видео+аудио) | $/час | Batch (50% скидка) |
|--------|---------------|---------------------|-------|-------------------|
| **Gemini 2.5 Flash** | **$0.005** | $0.006 | $0.36 | $0.18/час |
| Gemini 2.5 Pro (≤200k) | $0.019 | $0.021 | $1.26 | $0.63/час |
| Gemini 2.5 Pro (>200k) | $0.039 | $0.041 | $2.46 | $1.23/час |

### Gemini vs TwelveLabs: когда что

| Сценарий | Победитель | Почему |
|----------|-----------|-------|
| Одноразовый highlight detection | **Gemini Flash** | 12x дешевле ($0.005 vs $0.063/мин) |
| Точные таймкоды для автоматической нарезки | **TwelveLabs** | Video-native модель, лучше temporal grounding |
| Повторные запросы к библиотеке видео | **TwelveLabs** | Index once, query many ($4/1000 запросов) |
| Object tracking cross-frame | **TwelveLabs** | Архитектурное преимущество |
| Chapter generation | **Gemini Flash** | Достаточно качества, 12x дешевле |
| Semantic search | **TwelveLabs** | Единственный с pre-indexed vector search |
| Budget MVP | **Gemini Flash** | Минимальная стоимость входа |

### GPT-4o/4.1 — не рекомендуется для видео

- **Нет нативного видеовхода** — нужно извлекать кадры (OpenCV/ffmpeg)
- 85 токенов/кадр (low detail), 765 токенов/кадр (high detail)
- $0.026-0.23/мин — **дороже Gemini при худшем качестве**
- Нет аудио из видео (отдельный Whisper)
- Нет встроенных таймкодов
- GPT-4.1: улучшен до 72% VideoMME, но фундаментальное ограничение (кадры) остаётся

---

## 7. Clipping-платформы

### Сравнение API-доступности

| Платформа | API | Цена API | Highlights | Captions | Reframe | Batch | RU |
|-----------|-----|----------|-----------|----------|---------|-------|-----|
| **OpusClip** | Enterprise only | Custom | ✅ 95%+ mAP | ✅ | ✅ | 50 concurrent | Нет |
| **Reap.video** | Все планы ($9.99+) | Включена | ✅ Multi-signal | ✅ 98 языков | ✅ | 5-15 concurrent | ✅ |
| **Vizard** | Paid планы ($20+) | Включена | ✅ | ✅ 100+ языков | ✅ | Minimal API | Неизвестно |
| **Descript** | Нет public API | — | ✅ "Find Good Clips" | ✅ | ✅ | — | Нет |
| **CapCut** | Нет public API | — | ✅ Smart Highlights | ✅ | ✅ | — | Частично |

### OpusClip — подробнее

- **ClipAnything**: мультисигнальный AI (визуал + аудио + сентимент), mAP 0.93
- **Virality Score**: 0-100 эвристика, спорная точность (клипы с низким скором часто работают лучше)
- **API**: Enterprise-only, 30 req/мин, макс 10 часов видео
- **Цены SaaS**: Free 60 мин/мес → Starter $15 (150 мин) → Pro $14.50/мес (annual, 3600/год)
- **Барьер**: API недоступен на обычных планах

### Reap.video — неожиданно сильный

- **API + CLI + MCP** за $9.99/мес — значительно доступнее OpusClip
- **MCP Server** — прямая интеграция с Claude Code и другими AI-агентами
- **Prompt-first clipping**: опиши какие клипы хочешь — AI найдёт
- **98 языков** включая русский для субтитров
- **80 языков** для дубляжа (русский включён)
- **Romanized scripts** (Hinglish, Arabizi) — уникальная фича

### Конкурентная карта (Product Lead)

```
                 ВЫСОКАЯ ЦЕНА
                    |
         Descript   |   (Enterprise)
         $24-35/мес |
                    |
    OpusClip $29    |
                    |
    Vizard $20-30---+--- ☕ Coffee Project TARGET: $15-29/мес
                    |     Субтитры + Клипы в одном
                    |
   Reap $9.99       |
                    |
         CapCut     |
         $8-20      |
                    |
                 НИЗКАЯ ЦЕНА
                    |
   ТОЛЬКО СУБТИТРЫ -------------- ПОЛНЫЙ REPURPOSING
```

**Позиционирование Coffee Project**: «Единственный инструмент, где субтитры И клипы — first-class citizens в одном workflow, по цене ниже full-editor tax.»

---

## 8. B-Roll генерация

### Text-to-Video модели: текущее состояние

| Модель | Качество | Длительность | $/5-сек клип | Готово для B-Roll? |
|--------|----------|-------------|-------------|-------------------|
| **Runway Gen-4 Turbo** | Хорошее, быстрое | 5-10 сек | $0.25 | Почти, но артефакты |
| **Runway Gen-4.5** | Выше | 5-10 сек | $0.60 | Ближе |
| **Runway Gen-4 Aleph** | Наивысшее (Runway) | 5-10 сек | $0.75 | Ближе |
| **Pika 2.2** (via fal.ai) | Хорошее для соцсетей | 5 сек | **$0.20** | Для некритичного контента |
| **Kling 2.6** | Отличное для природы | 5-10 сек | $0.45-0.50 | Для ландшафтов да |
| **Veo 3.1** (Runway API) | Сильное | 5-10 сек | $1.00 | Дорого |

### Честная оценка ML/AI-инженера: генерация НЕ готова

**Нет, ещё не для профессионального использования.** Причины:

1. **Консистентность**: каждая генерация независима. Нельзя получить два клипа с одинаковым освещением, локацией, камерой.
2. **Длительность**: 5-10 секунд. Реальный B-Roll — 15-60 секунд. Нужно цепочку генераций, что усиливает проблему консистентности.
3. **Артефакты**: даже Runway Gen-4 даёт нарушения физики, несоответствие освещения, «AI-маркеры».
4. **Стоимость**: 5-10 B-Roll клипов × $0.50 (+ 2-3 перегенерации) = $7.50-15 за видео. Стоковое видео дешевле.

### Рекомендация: AI-powered поиск стокового видео

| Сервис | Цена | Библиотека | API | Semantic Search |
|--------|------|-----------|-----|-----------------|
| **Pexels API** | **Бесплатно** | ~150K видео | Да, хорошая документация | Базовый keyword |
| **Storyblocks API** | Подписка | 1M+ видео | Да | Лучшая категоризация |
| **Shutterstock API** | Per-download / подписка | Крупнейшая | Да | AI-powered search |

**Phase 1 (запустить сейчас): Pexels API.**

Pipeline:
1. Транскрипция даёт текстовые сегменты с таймкодами
2. Gemini Flash анализирует сегменты → предлагает ключевые слова для B-Roll
3. Pexels API ищет подходящее стоковое видео
4. Пользователь выбирает из предложений

Бесплатно, реальное видео выглядит профессионально, можно запустить за недели.

**Phase 2 (когда модели созреют): AI-generated B-Roll как premium-опция.** Revisit в Q3 2026 с Runway Gen-5 / Veo 4.

---

## 9. Архитектура интеграции в Coffee Project

### Текущий pipeline (recap)

```
Upload → S3 → Media Probe (ffprobe) → Transcription (Whisper/Google) → Captions (Remotion) → S3
                                                                           ↕
                                                               Silence Detection (pydub)
```

**Что есть:**
- 2 STT-движка: LOCAL_WHISPER (default `tiny` — плохое качество), GOOGLE_SPEECH_CLOUD
- Dramatiq actors для всех фоновых задач с webhooks + WebSocket notifications
- Пустое поле `semantic_tags` в `WordNode` — готово для ML-аннотаций
- Silence detection (pydub + librosa)

**Чего нет:**
- Highlight/chapter detection
- Semantic search
- Video intelligence интеграция
- Монетизация (планы, квоты, биллинг)

### Новый модуль: `video_intelligence`

Backend-архитектор рекомендует **один новый модуль** со стандартной 6-файловой структурой:

```
cpv3/modules/video_intelligence/
    __init__.py
    models.py        # VideoIndex model
    schemas.py       # Index, Highlight, Chapter, Search schemas
    repository.py    # VideoIndexRepository
    service.py       # Provider calls, business logic
    router.py        # API endpoints
```

### Модель данных

```python
class VideoIndex(Base, BaseModelMixin):
    user_id: UUID                    # FK users
    project_id: UUID | None          # FK projects
    source_file_id: UUID             # FK files
    provider: str                    # "TWELVE_LABS" | "GEMINI"
    provider_index_id: str           # Provider-specific ID
    provider_video_id: str           # Provider video ref
    highlights_json: dict | None     # Cached highlights (JSONB)
    chapters_json: dict | None       # Cached chapters (JSONB)
    index_status: str                # PENDING | INDEXING | READY | FAILED
    video_duration_seconds: float
    indexing_cost_cents: int | None   # Cost tracking
```

Highlights и chapters — JSONB-колонки (не отдельные таблицы), по аналогии с `Transcription.document`.

### Расширенный pipeline

```
Upload → S3 → Media Probe
                    |
        +-----------+-----------+
        |                       |
   Transcription           Video Index (user-triggered)
   (Whisper/Scribe)       (TwelveLabs/Gemini)
        |                       |
        |              +--------+--------+
        |              |        |        |
        |         Highlights  Chapters  Search
        |         (Dramatiq)  (Dramatiq) (sync endpoint)
        |              |        |
        +------+-------+--------+
               |
          Shorts/Clips Rendering (Remotion)
```

### Режимы операций

| Операция | Режим | Почему |
|----------|-------|-------|
| Video indexing | **Dramatiq (async)** | Минуты обработки |
| Highlight detection | **Dramatiq (async)** | 30-60 сек |
| Chapter generation | **Dramatiq (async)** | 30-60 сек |
| Semantic search | **Sync endpoint** | 1-3 сек ответ |
| B-Roll suggestions | **Sync endpoint** | Быстрый поиск |

### Новые endpoints

**Task endpoints** (async, в `tasks/router.py`):
```
POST /api/tasks/video-index/           → 202 Accepted
POST /api/tasks/highlights-detect/     → 202 Accepted
POST /api/tasks/chapters-generate/     → 202 Accepted
```

**Sync endpoints** (в `video_intelligence/router.py`):
```
GET  /api/video-intelligence/{id}/              → VideoIndexRead
GET  /api/video-intelligence/{id}/highlights/   → HighlightsResult
GET  /api/video-intelligence/{id}/chapters/     → ChaptersResult
POST /api/video-intelligence/search/            → VideoSearchResponse
POST /api/video-intelligence/broll-suggestions/  → BRollSuggestionResponse
```

### Квоты и контроль расходов

Redis-based per-user quotas:
```python
# Проверка ПЕРЕД созданием Dramatiq task
QUOTA_FREE_INDEX_MINUTES = 60
key = f"vi_quota:{user_id}:indexed_minutes"

# Кэш поисковых запросов (5 мин TTL)
key = f"vi_search_cache:{video_index_id}:{sha256(query)[:16]}"
```

### Ключевые архитектурные решения

1. **НЕТ автоматической цепочки задач.** Frontend контролирует workflow — каждая задача запускается явно.
2. **НЕТ абстрактного провайдер-паттерна** (YAGNI). Простой string selector как в transcription engine.
3. **Retry с backoff для внешних API** (`max_retries=3, min_backoff=15000`) — в отличие от текущих actors с `max_retries=0`.
4. **Highlights/chapters кэшируются в БД** (JSONB). Search кэшируется в Redis (5 мин TTL).

---

## 10. Remotion Pipeline — эволюция

### Shorts/Clips рендеринг

**Гибридный подход FFmpeg + Remotion (2-3x быстрее чистого Remotion):**

| Шаг | Инструмент | Время | Зачем |
|-----|-----------|-------|-------|
| 1. Вырезать клип | FFmpeg `-c copy` | ~1 сек | Stream copy, без перекодирования |
| 2. Рендер с субтитрами | Remotion `ShortVideo` | 10-30 сек на клип | Каппинг + reframe + стили |
| 3. Upload | S3 multipart | ~5 сек | В папку `shorts/` |

**Сравнение для 10-мин видео → 5 Shorts по 1 мин:**

| Подход | Общее время | Ресурсы |
|--------|------------|---------|
| Чистый Remotion (5 рендеров от полного видео) | 5-10 мин | Высокие: 5 Chromium процессов, каждый ищет в 10-мин видео |
| **Гибрид** (FFmpeg нарезка + 5 лёгких рендеров) | **2-5 мин** | Средние: FFmpeg ~5 сек + 5 лёгких Remotion |
| Чистый FFmpeg (без субтитров) | ~10 сек | Минимальные |

### Новая композиция: `ShortVideo`

```typescript
type ShortCompositionProps = {
  videoSrc: string;
  transcription: Transcription;
  fps: number;
  styleConfig?: CaptionStyleConfig;
  clipStart: number;          // Начало в секундах
  clipEnd: number;            // Конец в секундах
  cropConfig?: {
    focusX: number;           // 0-1, центр кропа
    focusY: number;
    autoReframe: boolean;
  };
};
```

**Адаптация субтитров для вертикального формата:**
- Шрифт: 60-70px (вместо 40)
- Строки на экране: 1, макс 3-4 слова
- Позиция: bottom с отступом 80-100px (UI YouTube Shorts/TikTok/Reels перекрывает низ)
- Max width: 95% от 1080px
- Фон: более непрозрачный

**Auto-reframe:**
- Phase 1: Center crop (простейший, 607x1080 из 1920x1080)
- Phase 2: Speaker-position crop (per-segment `focusX` из ML)
- Phase 3: Per-frame face tracking (future)

### Chapter markers

Простой overlay — НЕ реструктуризация видео:
- `ChapterOverlay` компонент: fade-in заголовок, hold 2 сек, fade-out
- `interpolate()` для анимации (не CSS transitions)
- YouTube chapters metadata — ответственность backend, не Remotion

### B-Roll в Remotion

Самая сложная фича — мультиисточниковый таймлайн:

```typescript
type BRollSegment = {
  src: string;              // S3 presigned URL
  startTime: number;        // Когда показать
  endTime: number;
  mode: "cutaway" | "pip";  // Полная замена или overlay
  transitionIn?: "fade" | "slide" | "cut";
  audio: "mute" | "duck" | "replace";
};
```

- Использовать `<OffthreadVideo>` (не `<Video>`) — декодирование off-thread
- Docker может потребовать увеличение памяти: 4GB → 6-8GB
- Горизонтальное масштабирование: N контейнеров на одной BullMQ очереди

### Pre-existing bug

`remotion_service/src/themes/default.css:23` — CSS `transition: transform 0.1s ease;` на `.word`. Это browser timer, не Remotion frame clock. В CSS theme mode анимация scale на `.current-word` рендерится непредсказуемо. Inline style mode (с `styleConfig`) не затронут — это основной продакшн-путь.

---

## 11. Продуктовая стратегия и монетизация

### Критическая находка: нулевая инфраструктура монетизации

В кодовой базе **нет**:
- Поля `plan` / `subscription` в User модели
- Трекинга использования (минуты рендера, транскрипции)
- Квот и лимитов
- Интеграции с платёжными системами
- Pricing page / upgrade modal

Это **блокер** для любых платных фич.

### Рекомендуемая тарифная сетка

| | Free | Starter ($15/мес) | Pro ($29/мес) | Agency ($79/мес) |
|---|---|---|---|---|
| Минуты обработки | 30/мес | 150/мес | 400/мес | 1,200/мес |
| Транскрипция | Whisper base | Все движки | Все движки | + приоритет |
| Стили субтитров | 3 базовых | 10 | Все | + кастомный бренд |
| Клипы с видео | Preview only | 5/видео | Безлимит | Безлимит |
| Chapters | Да (бесплатно) | Да | Да | Да |
| Качество экспорта | 720p + watermark | 1080p | 4K | 4K |
| Highlights engine | Transcript-based | Gemini Flash | TwelveLabs | TwelveLabs + analytics |
| API доступ | Нет | Нет | Нет | Да |
| Команда | 1 | 1 | 1 | 5 |

### Unit economics

**Стоимость за минуту обработки:**

| Компонент | $/мин |
|-----------|-------|
| TwelveLabs indexing | $0.042 |
| TwelveLabs infrastructure | $0.0015/мес |
| TwelveLabs search | ~$0.004 |
| Whisper STT (self-hosted) | ~$0.0005 |
| Remotion render (clip) | ~$0.02 |
| S3 storage (amortized) | ~$0.001 |
| **С TwelveLabs** | **~$0.07** |
| **Без TwelveLabs (Gemini)** | **~$0.03** |

**Маржинальность по тарифам:**

| Тариф | Revenue | Avg usage | Cost (с TwelveLabs) | Gross Margin |
|-------|---------|-----------|--------------------|--------------|
| Starter $15 | $15 | ~80 мин | $5.60 | **63%** |
| Pro $29 | $29 | ~200 мин | $14.00 | **52%** |
| Agency $79 | $79 | ~600 мин | $42.00 | **47%** |

### Free tier: TwelveLabs НЕ использовать

Free tier должен использовать **transcript-based highlights** (анализ энергии + ключевых слов из транскрипции) — почти нулевая стоимость. TwelveLabs — только для платных тарифов.

10,000 free users × $2.10/мес TwelveLabs = $21,000/мес. Без TwelveLabs = ~$900/мес.

### Конкурентное позиционирование

| Инструмент | За ~150 мин/мес + субтитры + клипы | Coffee Project эквивалент |
|------------|-----------------------------------|--------------------------|
| OpusClip Starter | $15/мес (клипы, без субтитров) | $15/мес (субтитры + клипы) |
| Vizard Creator | $14.50-30/мес | $15/мес (лучше субтитры) |
| Descript Hobbyist | $24/мес (полный редактор) | $15/мес (focused workflow) |
| Reap | $9.99/мес | $15/мес (больше обработки) |

### Русский рынок

- **Нет локальных конкурентов** в AI video clipping
- Западные инструменты: проблемы с оплатой (Stripe недоступен)
- Платёжные системы: ЮKassa, CloudPayments, Тинькофф
- Цены: ₽990/мес (Starter), ₽1,990/мес (Pro) — на 30-50% ниже USD
- Каналы: VK, Telegram, YouTube (через VPN)

---

## 12. Сводная таблица стоимости

### Расчёт для 100 часов видео/мес (обновлённый)

| Стек | $/мес | Что получаем |
|------|-------|-------------|
| **Gemini 2.5 Flash** (highlights + chapters) | **~$36** | Highlight detection + chapters. Без search |
| **TwelveLabs** (index + infra + analyze + search) | ~$389 | Полный video understanding + semantic search |
| **Gemini Flash + TwelveLabs search** (гибрид) | ~$180 | Flash для анализа, TL для поиска по библиотеке |
| **DeepInfra Whisper** (STT draft) | ~$6 | Черновая транскрипция |
| **ElevenLabs Scribe** (STT prod) | ~$40 | Продакшн транскрипция |
| **Pexels API** (B-Roll search) | **$0** | Поиск стокового видео |
| **Google Video Intelligence** (labels + shots) | ~$450-600 | Метаданные, без highlights |

### Рекомендуемый стек по фазам

| Фаза | Стек | $/мес (100 часов) |
|------|------|-------------------|
| **MVP** | Gemini Flash + DeepInfra Whisper + Pexels | **~$42** |
| **Growth** | Gemini Flash + Scribe v2 + TwelveLabs search | **~$220** |
| **Scale** | TwelveLabs full + Scribe v2 + Pexels + Runway | **~$470** |

---

## 13. Рекомендации и дорожная карта

### Приоритеты (RICE-скоринг от Product Lead)

| Приоритет | Фича | Движок | Effort (dev-weeks) | $/мес (100 users) |
|-----------|-------|--------|--------------------|--------------------|
| **P0** | Upgrade STT → Scribe v2 | ElevenLabs API | 2-3 дня | $40-80 |
| **P0** | Draft STT tier | Whisper v3-turbo (DeepInfra) | 2-3 дня | $6-12 |
| **P0** | Монетизация (планы, квоты, биллинг) | Stripe + ЮKassa | 4-6 недель | — |
| **P1** | Highlight detection MVP | Gemini 2.5 Flash | 1 неделя | $5-15 |
| **P1** | Shorts rendering | FFmpeg + Remotion ShortVideo | 2-3 недели | — |
| **P2** | Chapter generation | Gemini 2.5 Flash | 1 неделя | $5 |
| **P2** | B-Roll suggestions (stock) | Pexels API + Gemini Flash | 2 недели | $5 + $0 |
| **P3** | Premium highlights | TwelveLabs Pegasus 1.2 | 1 неделя | $50-200 |
| **P3** | Semantic video search | TwelveLabs Marengo 3.0 | 2 недели | $20-50 |
| **P4** | AI-generated B-Roll | Runway Gen-4 API | 1 неделя | Variable |

### Фазы реализации

**Pre-Phase: Монетизация (4-6 недель, параллельно с Phase 1)**
- `plan`, `plan_expires_at`, `usage_minutes_current/limit` в User модели
- Usage tracking middleware
- Quota enforcement в service layer
- Stripe Checkout + ЮKassa
- Pricing page + upgrade modal

**Phase 1: «Clips» — Highlights + Smart Clipping (8-10 недель)**
- `video_intelligence` модуль
- Gemini Flash интеграция для highlight detection
- Shorts rendering (ShortVideo composition + FFmpeg pre-cut)
- Субтитры на клипах (существующие стили)
- Free tier: transcript-based highlights (preview only, без экспорта)
- Paid: Gemini Flash highlights + экспорт клипов

**Phase 2: Chapters + B-Roll suggestions (4-6 недель)**
- Chapter generation через Gemini Flash
- Chapter overlay в Remotion
- YouTube chapters metadata export
- Pexels API для B-Roll suggestions
- Chapters — бесплатно (activation feature)

**Phase 3: Premium Video Intelligence (future)**
- TwelveLabs для premium highlight detection
- Semantic video search (enterprise)
- Prompt-first clipping
- Batch processing

---

## 14. Красные флаги в текущем коде

Обнаружено агентами при анализе кодовой базы:

### Backend

1. **Whisper default model = `tiny`** (`schemas.py:122`, `service.py:325`). Минимум `base` или `small` для приемлемого качества.

2. **Нет `time_limit` на Dramatiq actor** (`@dramatiq.actor(max_retries=0)`, `service.py:603`). Corrupted файл может заставить воркер висеть бесконечно. Добавить `time_limit=1800000` (30 мин).

3. **Google Speech V1 API**. V2 API имеет модель Chirp — значительно лучше для мультиязычного контента.

4. **Нет кэширования транскрипций**. Actor не проверяет, существует ли транскрипция для того же файла + движка + модели + языка. Повторная транскрипция = потеря денег.

5. **Transcription router обходит service layer** (`transcription/router.py:30-38`) — прямой вызов `TranscriptionRepository` из router. Нарушает паттерн Router → Service → Repository.

6. **Нет пагинации** на `list_all_transcriptions` — возвращает неограниченный список.

7. **Inline error strings** (`transcription/router.py:65`: `detail="Не найдено"`) — нет `ERROR_` константы.

8. **`tasks/service.py` уже 1400+ строк** — новые actors должны делегировать в `video_intelligence/service.py`.

### Remotion

9. **CSS `transition` в `default.css:23`** — `transition: transform 0.1s ease;` на `.word` класс. Browser timer, не Remotion frame clock. Непредсказуемый рендеринг в CSS theme mode.

10. **`<Video>` вместо `<OffthreadVideo>`** — для B-Roll с множественными видеоисточниками нужен `<OffthreadVideo>` (декодирование off-thread).

11. **Docker лимиты**: 2 CPU, 4GB RAM, `MAX_CONCURRENT_RENDERS=2`. Shorts batch + B-Roll потребуют увеличения до 6-8GB.

---

## 15. Источники

### STT
- [Artificial Analysis STT Leaderboard](https://artificialanalysis.ai/speech-to-text)
- [ElevenLabs Scribe v2](https://elevenlabs.io/blog/introducing-scribe-v2)
- [ElevenLabs Scribe v2 Realtime](https://elevenlabs.io/blog/scribe-v2-realtime-in-elevenlabs-agents)
- [ElevenLabs API Pricing](https://elevenlabs.io/pricing/api)
- [Deepgram Nova-3 Introduction](https://deepgram.com/learn/introducing-nova-3-speech-to-text-api)
- [Deepgram Nova-3 Multilingual WER](https://deepgram.com/learn/nova-3-multilingual-major-wer-improvements-across-languages)
- [Deepgram Models & Languages](https://developers.deepgram.com/docs/models-languages-overview)
- [Deepgram Pricing](https://deepgram.com/pricing)
- [Whisper large-v3-turbo (HuggingFace)](https://huggingface.co/openai/whisper-large-v3-turbo)
- [Whisper large-v3-russian (fine-tuned)](https://huggingface.co/antony66/whisper-large-v3-russian)
- [DeepInfra Whisper API](https://deepinfra.com/openai/whisper-large-v3-turbo/api)

### Video Intelligence
- [TwelveLabs Pricing](https://www.twelvelabs.io/pricing)
- [TwelveLabs Docs](https://docs.twelvelabs.io)
- [TwelveLabs Marengo 3.0](https://www.twelvelabs.io/blog/marengo-3-0)
- [TwelveLabs Pegasus 1.2](https://www.twelvelabs.io/blog/introducing-pegasus-1-2)
- [TwelveLabs Video-to-Text Arena](https://www.twelvelabs.io/blog/video-to-text-arena)
- [TwelveLabs Developer Experience (GitHub)](https://github.com/twelvelabs-io/twelvelabs-developer-experience)
- [Gemini 2.5 Video Understanding](https://developers.googleblog.com/en/gemini-2-5-video-understanding/)
- [Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
- [GPT-4.1 Multimodal](https://blog.roboflow.com/gpt-4-1-multimodal/)
- [Google Video Intelligence API](https://cloud.google.com/video-intelligence)

### Clipping Platforms
- [OpusClip API](https://help.opus.pro/api-reference/overview)
- [OpusClip Pricing](https://www.opus.pro/pricing)
- [Reap.video API](https://docs.reap.video/api-reference/1_introduction)
- [Reap.video MCP](https://reap.video/mcp)
- [Vizard API Docs](https://docs.vizard.ai/docs/introduction)
- [Descript Pricing](https://www.descript.com/pricing)
- [CapCut Pricing](https://www.gamsgo.com/blog/capcut-pricing)

### B-Roll Generation
- [Runway API Pricing](https://docs.dev.runwayml.com/guides/pricing/)
- [Pika 2.2 on fal.ai](https://fal.ai/models/fal-ai/pika/v2.2/text-to-video)
- [Kling AI Pricing](https://klingai.com/global/dev/pricing)
- [Best Text-to-Video APIs 2026](https://wavespeed.ai/blog/posts/best-text-to-video-api-2026/)
- [Pexels Free API](https://www.pexels.com/api/)

### Market & Competition
- [AI Video Generator Market (Grand View Research)](https://www.grandviewresearch.com/industry-analysis/ai-video-generator-market-report)
- [Descript vs Veed vs Kapwing Growth (YipitData)](https://www.yipitdata.com/resources/blog/descript-vs-veed-vs-kapwing-ai-video-tools)
- [OpusClip Highlight Accuracy](https://www.opus.pro/blog/ai-tools-for-precise-video-highlight-search-accuracy)
- [SaaS Freemium Conversion Benchmarks](https://firstpagesage.com/seo-blog/saas-freemium-conversion-rates/)

---

*Документ подготовлен 8 параллельными исследовательскими агентами: 4 внешних ресёрчера (TwelveLabs repo, TwelveLabs pricing, Other Services, Coffee Architecture) + 4 доменных специалиста (ML/AI Engineer, Backend Architect, Product Lead, Remotion Engineer).*