# Тексты

> Факты, вопросы с ответами и цитаты о тайтле.

> Оглавление документации для агентов: https://kinodata.space/ru/llms.txt — вся документация одним файлом: https://kinodata.space/ru/llms-full.txt

Запрос: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/texts`

Без параметров тексты приходят разделами: факты, вопросы и ответы, цитаты. `counts` — сколько текстов каждого вида у тайтла, при любом `kind`: по нему подписываются вкладки.

Тексты сейчас только на русском: поля `_en` равны `null`. С `lang=en` текст придёт пустым — так видно, что перевода ещё нет.

У «Матрицы» сюжет раскрывает каждый четвёртый факт. Чтобы показывать факты рядом с описанием, уберите спойлеры: `spoilers=false`.

## Параметры пути

- `type` (string, обязательный) — Каталог, из которого ID: IMDb, Кинопоиск, TMDB (фильм или сериал) или Кинориум.
  Значения: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, обязательный) — ID в этом каталоге. У IMDb — `tt` и цифры (`tt1375666`), у остальных — цифры (`447301`).

## Параметры запроса

- `kind` (csv) — Виды текстов, через запятую. Подписи — в `/enums`, набор `text_kinds`.
  Значения: `fact`, `faq`, `quote`.
  По умолчанию: все три. Пример: `kind=quote`.
- `spoilers` (boolean) — `false` — убрать факты, которые раскрывают сюжет.
  По умолчанию: со спойлерами. Пример: `spoilers=false`.
- `fact_kind` (csv) — Подвиды фактов, через запятую. Подписи — в `/enums`, набор `fact_kinds`.
  Значения: `general`, `trivia`, `blooper`.
  Пример: `fact_kind=blooper`.
- `group` (enum) — Разбить список на разделы. `none` — плоский список. Как устроены разделы — в [Списки и пагинация](https://kinodata.space/ru/docs/lists.md#разделы).
  Значения: `kind`, `none`.
  По умолчанию: `kind`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько элементов вернуть, целое от 1. В разделах — на каждый раздел, до 50. В плоском списке — до 1000. Больше потолка — не ошибка: API срежет до него и покажет в `limit`.
  По умолчанию: 10 в разделе, 1000 в плоском списке. Пример: `limit=20`.
- `offset` (integer) — Сколько элементов пропустить, целое от 0. Только в плоском списке: с разделами — `400`.
  По умолчанию: 0.

## Поля ответа

- `counts` (object) — Сколько у тайтла фактов, вопросов и цитат: `fact`, `faq`, `quote`.
- `items` (array) — Тексты. Набор полей зависит от вида — `kind`. В разделах — разделы со своими `total` и подписями.
  - `kind` (enum) — Вид: `fact`, `faq` или `quote`.
  - `text_ru`, `text_en` (string | null) — Факт или цитата.
  - `fact_kind` (enum) — Подвид факта: `general` — факт, `trivia` — интересный факт, `blooper` — киноляп.
  - `is_spoiler` (boolean) — Факт раскрывает сюжет. `false` — источник его так не пометил.
  - `ord` (integer) — Порядок факта у источника.
  - `question_ru`, `question_en`, `answer_ru`, `answer_en` (string | null) — Вопрос и ответ.
  - `links` (array) — Кто упомянут в ответе: `text` — как написано, `type` и ID с именем, как у человека в составе.
  - `original`, `original_lang` (string | null) — Цитата на языке оригинала и этот язык, ISO 639-1.
  - `author_ru`, `author_en` (string | null) — Кто произносит цитату — актёр.
  - `author_role_ru`, `author_role_en` (string | null) — Персонаж, которому принадлежит цитата.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `kind`, `fact_kind` или `group`; `offset` вместе с разделами; параметр, которого этот список не понимает (например, `sort` или `fields`) — в ответе список допустимых. |
| 404 | `not_found` | Тайтл с таким ID не найден. |
| 401 | `unauthorized` | Нет заголовка `X-API-Key`, ключ неизвестен или отозван. |
| 429 | `rate_limited` | Исчерпан предел в секунду или квота на сутки. |

Все коды и что с ними делать — на странице [Ошибки](https://kinodata.space/ru/docs/errors.md).

## Примеры

### Цитаты

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=quote" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Ответ `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "author_ru": "Роуэн Уитт",
      "author_en": null,
      "author_role_ru": "мальчик с ложкой",
      "author_role_en": null,
      "kind": "quote",
      "original": "There is no spoon.",
      "original_lang": "en",
      "text_ru": "Ложки не существует.",
      "text_en": null
    },
    {
      "author_ru": "Киану Ривз",
      "author_en": null,
      "author_role_ru": "Нео",
      "author_role_en": null,
      "kind": "quote",
      "original": "I know kung fu.",
      "original_lang": "en",
      "text_ru": "Я знаю кунг-фу.",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 5
}
```

### Факты

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=fact" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Ответ `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "fact_kind": "blooper",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 64,
      "text_ru": "В эпизоде, где Тринити и Нео в поисках Морфиуса оказываются на крыше, один из пилотов вертолета трансформируется в агента Джонса. При этом левый висок Джонса приходится на затылок пилота. Однако после выстрела Тринити именно в этот висок, пулевое отверстие у пилота, покинутого «программой» агента, почему-то оказывается во лбу.",
      "text_en": null
    },
    {
      "fact_kind": "blooper",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 65,
      "text_ru": "В сцене, когда Нео впервые встречается с Морфиусом, герой Лоренса Фишбёрна здоровается с Избранным. Морфиус протягивает правую руку, при этом левая рука у него за спиной. Далее сразу же следует вставка с другого ракурса, где левая рука уже почему-то опущена к полу. В следующем кадре левая рука Морфиуса снова за спиной.",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 100
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=faq" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Ответ `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "answer_ru": "Фильм следует за Томасом Андерсоном, который начинает подозревать, что привычная реальность — лишь тщательно сконструированная иллюзия. Встреча с Морфеусом и его командой втягивает героя в конфликт с системой контроля и её агентами, заставляя выбирать между комфортной ложью и рискованной правдой.",
      "answer_en": null,
      "kind": "faq",
      "links": [],
      "question_ru": "О чём фильм «Матрица» без спойлеров концовки?",
      "question_en": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 14
}
```

### Только английский

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=quote" \
  --data-urlencode "limit=2" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Ответ `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "author_en": null,
      "author_role_en": null,
      "kind": "quote",
      "original": "There is no spoon.",
      "original_lang": "en",
      "text_en": null
    },
    {
      "author_en": null,
      "author_role_en": null,
      "kind": "quote",
      "original": "I know kung fu.",
      "original_lang": "en",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 5
}
```