grabber-ai/docs/api-reference.md

# Справочник API: значения ответа и принцип работы

Этот документ — единственное место, где перечислены все возможные значения полей ответа. **Заглядывать
в `data/labels.csv` для этого не нужно**: файл большой (десятки МБ), нужен только при обучении и в
работе сервиса не участвует. Список классов модели хранится в `models/best/label_maps.json`
(в образе — `/app/models/best/label_maps.json`) и отдаётся сервисом: `GET /health` → `classes`.

Запросы, переменные окружения и запуск — в [docker.md](docker.md); формат вызова из кода —
в [integration.md](integration.md); CLI и Python API — в [inference.md](inference.md).

## Эндпоинты

| Метод | Путь | Назначение |
|---|---|---|
| GET | `/health` | статус, модель, список классов `classes`, режим сегментатора, `flaresolverr`, `auth`. Токен не нужен |
| POST | `/predict` | предсказание. Тело — JSON с **ровно одним** из полей `text`, `html`, `url` |
| GET | `/docs` | интерактивная Swagger-документация FastAPI |

Тело `/predict`:

| Поле | Тип | Описание |
|---|---|---|
| `text` | string | одна дорожка (строка вида «Профессиональный (многоголосый закадровый) \| LostFilm») → ответ `{"tracks": [одна дорожка]}` |
| `html` | string | HTML (или текст) страницы раздачи → ответ-агрегат релиза |
| `url` | string | ссылка на раздачу rutracker / nnmclub / kinozal; страницу сервис скачивает сам (при 403/503 — через FlareSolverr) → ответ-агрегат + `tracker` |
| `title` | string, необязательно | заголовок раздачи для `html` (во фрагменте вкладки его нет); для `url` берётся со страницы |
| `cookie` | string, необязательно | Cookie для `url` (kinozal требует авторизацию) |

Коды ошибок: `400` — неверное тело, пустой текст, страница не разобрана или запрещённый хост;
`401` — нет/неверный токен (если задан `DUB_API_TOKEN`); `502` — не удалось скачать страницу.
Токен передаётся `Authorization: Bearer <токен>` или `X-API-Key: <токен>`.

## Ответ релиза (`html` и `url`)

```json
{
  "tracks": [ /* дорожки, см. ниже */ ],
  "studios": [{"studio": "LostFilm", "translation_type": "проф. многоголосый", "is_18plus": false, "episodes": "1-4"}],
  "translation_types": ["проф. многоголосый"],
  "is_18plus": false,
  "series": {"season": "2", "episodes": "1-9", "total": 10, "by_studio": {"LostFilm": "1-4"}, "full_release": []},
  "title": "Название раздачи",
  "segmenter": "model",
  "tracker": "rutracker"
}
```

| Поле | Тип | Описание |
|---|---|---|
| `tracks` | array | дорожки релиза без дублей (дубль — одинаковые тип + студия) |
| `studios` | array | уникальные `{studio, translation_type, is_18plus, episodes}` |
| `translation_types` | array of string | отсортированный набор типов (значения — из таблицы классов ниже) |
| `is_18plus` | bool | `true`, если 18+ хотя бы у одной дорожки |
| `series` | object \| null | сезон, выпущенные серии, «какая студия какие серии» (для Sonarr); `null` — сведений нет |
| `title` | string \| null | заголовок раздачи, если найден |
| `segmenter` | `"model"` \| `"rules"` | чем страница разбита на строки дорожек: обученным сегментатором или запасными правилами |
| `tracker` | string | только для `url`: `rutracker`, `nnmclub` или `kinozal` |

`series`: `season` — номер сезона строкой или `null`; `episodes` — выпущенные серии («1-9»);
`total` — всего серий; `by_studio` — `{студия: серии}`; `full_release` — студии без указанных серий
(для сериала это значит «озвучены все вышедшие серии»). Подробности — в [integration.md](integration.md).

## Дорожка (элемент `tracks`)

| Поле | Тип | Значения / описание |
|---|---|---|
| `segment` | string | текст дорожки, по которому сделано предсказание |
| `translation_type` | string | **один из 14 классов** — [таблица ниже](#translation_type-14-классов) |
| `type_confidence` | float 0..1 | вероятность выбранного класса |
| `studio_span` | string \| null | фрагмент текста, распознанный как автор/студия |
| `studio` | string \| null | каноническое имя автора из словаря алиасов; неизвестное имя возвращается как в тексте; `null` — автора нет |
| `studio_confidence` | float \| null | средняя вероятность токенов спана |
| `is_18plus` | bool | дорожка помечена 18+ (по модели или по строке «Аудио … 18+» страницы) |
| `age_confidence` | float 0..1 | вероятность предсказанного класса 18+ |
| `lang` | string \| null | язык дорожки, ISO-подобный 3-буквенный код: `RUS`, `UKR`, `ENG`, также `BEL`, `KAZ`, `POL`, `FRA`, `DEU`, `ITA`, `SPA`, `JPN`, `KOR`, `CHI`, `CZE`, `LAV`, `LIT`, `EST`, `GEO`, `ARM`, `AZE`, `UZB`, `TUR`, `POR`, `HIN`; `null` — не определён |
| `lang_confidence` | float \| null | уверенность модели; заполнено только при `lang_source = "model"` |
| `lang_source` | `"model"` \| `"audio"` \| `"text"` \| null | откуда язык: нейросеть (классы `ENG`/`RUS`/`UKR`, порог 0.5), строка «Аудио» страницы или слова в тексте («Украинский дубляж») |
| `role` | string | `перевод`, `оригинал` (оригинальная дорожка без озвучки) или `комментарии` (комментарии режиссёра и т. п.) |
| `official` | bool | в строке «Аудио» есть слова «официальный» / «лицензионный» / «licensed» |
| `audio` | object \| null | `{codec, channels, bitrate_kbps}` из строки «Аудио» страницы (`ac3`, `6`, `448`); каждое поле может быть `null`; весь объект `null`, если строка не найдена |
| `source` | `"page"` \| `"title"` | только в ответе релиза: дорожка найдена в описании или студия взята из заголовка раздачи |
| `episodes` | string \| null | серии, которые озвучивает дорожка («1-4», «1,3-5»); `null` — серии не указаны (покрывает весь релиз) |
| `episode_ranges` | array | то же в виде `[[1, 4]]`; пусто, если серий нет |

Поле `lang` описывает только язык дорожки; `role` и `lang` не зависят от `translation_type`.

### translation_type: 14 классов

Класс — составная метка «кто делал × сколько голосов». Других значений сервис не возвращает.

| Значение | Кто озвучивал | Вид |
|---|---|---|
| `проф. дубляж` | профессиональная студия | дубляж (речь актёров заменяет оригинал; в страницах «Дублированный») |
| `проф. многоголосый` | профессиональная студия | закадровый, три и более голоса |
| `проф. двухголосый` | профессиональная студия | закадровый, два голоса |
| `проф. одноголосый` | профессиональная студия | закадровый, один голос |
| `люб. многоголосый` | любительская озвучка | закадровый, три и более голоса |
| `люб. двухголосый` | любительская озвучка | закадровый, два голоса |
| `люб. одноголосый` | любительская озвучка | закадровый, один голос |
| `авт. многоголосый` | авторская (один автор / «авторский перевод») | закадровый, три и более голоса |
| `авт. двухголосый` | авторская | закадровый, два голоса |
| `авт. одноголосый` | авторская | закадровый, один голос |
| `многоголосый` | в тексте не сказано | закадровый, три и более голоса |
| `двухголосый` | в тексте не сказано | закадровый, два голоса |
| `одноголосый` | в тексте не сказано | закадровый, один голос |
| `неизвестно` | — | тип по тексту определить нельзя |

Как читать: префикс `проф.` / `люб.` / `авт.` — категория озвучивающего (на трекерах это слова
«Профессиональный», «Любительский», «Авторский»); без префикса — раздача не указывает категорию.
Для фильтров в приложении обычно достаточно сопоставить по префиксу и по хвосту (`…дубляж`,
`…многоголосый`, `…двухголосый`, `…одноголосый`). Классы с единичными примерами в обучении
распознаются хуже (см. [dataset.md](dataset.md)); при низком `type_confidence` (< 0.6) значению стоит
доверять осторожно. Состав и названия классов задаёт обучение; актуальный список для конкретной
модели — `GET /health` → `classes`.

## Принцип работы

1. **Получение страницы.** `url` скачивается самим сервисом: сначала напрямую, при 403/503 или
   Cloudflare-заглушке — через FlareSolverr (`DUB_FLARESOLVERR_URL`). Разрешены только rutracker,
   nnmclub и kinozal.
2. **HTML → текст** (BeautifulSoup: пост rutracker, вкладка описания kinozal, иначе весь документ).
3. **Сегментация.** Обученная модель-сегментатор (`models/segmenter`, rubert-tiny2) помечает строки
   страницы, в которых описана дорожка (`«Перевод: …»`, `«Аудио 2: …»`, перечисления студий).
   Если сегментатора нет или он ничего не нашёл — запасные правила (`"segmenter": "rules"`).
   Многодорожечные строки («1. … 2. …», «A + B») разбиваются на отдельные дорожки.
4. **Контекст аудио.** К тексту дорожки подмешивается подходящая строка «Аудио» страницы
   (кодек, каналы, битрейт, язык, 18+) в виде хвоста `[RUS AC3 6ch 448kbps 18+]`.
5. **Модель-классификатор** (`DubTagger` на основе ruBert-base, `models/best`) делает за один проход
   несколько предсказаний: `translation_type` (14 классов), спан автора (разметка BIO по токенам),
   флаг 18+ и язык (`ENG`/`RUS`/`UKR`).
6. **Постобработка.** Автор канонизируется словарём алиасов; 18+ ставится также по строке «Аудио»;
   язык: нейросеть → строка «Аудио» → слова в тексте; определяются `role`, `official`, `audio`.
7. **Агрегат релиза.** Дубли (тип + студия) склеиваются; студии из заголовка раздачи, которых нет
   в описании, добавляются с `source: "title"`; серии и сезон разбираются правилами (`src/episodes.py`).

Размеченные данные (`data/labels.csv`) используются только при обучении: на них учатся метки
`translation_type`, спан студии, 18+ и язык. Схема файла и происхождение меток — в
[dataset.md](dataset.md). Источник правды для набора классов во время работы — `label_maps.json`
рядом с весами модели.

## Пример

```bash
curl -s http://localhost:7654/predict -H "Authorization: Bearer <ТОКЕН>" \
     -H "Content-Type: application/json" \
     -d '{"text": "Профессиональный (многоголосый закадровый) | HDRezka Studio 18+"}'
```

```json
{"tracks": [{"segment": "Профессиональный (многоголосый закадровый) | HDRezka Studio 18+",
  "translation_type": "проф. многоголосый", "type_confidence": 0.99,
  "studio_span": "HDRezka Studio", "studio": "HDrezka", "studio_confidence": 0.97,
  "is_18plus": true, "age_confidence": 0.99,
  "lang": "RUS", "lang_confidence": null, "lang_source": "text",
  "role": "перевод", "official": false, "audio": null}]}
```

(значения `lang*` в примере иллюстративны: они зависят от модели и текста.)