# Медиа

> Постеры, кадры, логотипы и видео тайтла одним списком.

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

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

Изображения и видео приходят в одной форме. У изображения пусты `youtube_id`, `preview_url` и `runtime_sec`, у видео — `width` и `height`. Адреса полные: собирать ссылку из частей не нужно.

Медиатека бывает большой — у «Начала» 485 файлов. Сужайте её: `type=poster&language=ru` — постеры на русском, `class=video` — только видео, `group=type` — разделы с размерами.

Анимированный постер `poster_gif` числится изображением, но это ролик mp4 до 7 МБ. Показывайте его в `<video autoplay muted loop playsinline>` и грузите по требованию. Если он есть, он один и идёт первым.

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

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

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

- `class` (enum) — Только изображения или только видео.
  Значения: `image`, `video`.
  По умолчанию: оба.
- `type` (enum) — Вид файла. Изображения: `poster_gif`, `poster`, `backdrop`, `still`, `cover`, `logo`, `promo`, `backstage`, `other`. Видео: `trailer`, `teaser`, `tvspot`, `clip`, `interview`, `music_video`, `behind_scenes`, `blooper`, `overview`, `other`. `other` есть у обоих: чтобы выбрать одно, добавьте `class`. Подписи — в `/enums`, наборы `image_types` и `video_kinds`.
  По умолчанию: все. Пример: `type=poster`.
- `language` (string) — Язык надписей на изображении или звука в видео, код ISO 639-1.
  По умолчанию: все. Пример: `language=ru`.
- `group` (enum) — Разбить список на разделы. `none` — плоский список. Как устроены разделы — в [Списки и пагинация](https://kinodata.space/ru/docs/lists.md#разделы).
  Значения: `type`, `class`, `language`, `none`.
  По умолчанию: без разделов.
- `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.

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

- `items` (array) — Файлы. С `group` — разделы со своими `total` и подписями.
  - `class` (enum) — `image` или `video`.
  - `type` (enum) — Вид файла.
    Значения: `poster_gif`, `poster`, `backdrop`, `still`, `cover`, `logo`, `promo`, `backstage`, `other`, `trailer`, `teaser`, `tvspot`, `clip`, `interview`, `music_video`, `behind_scenes`, `blooper`, `overview`.
  - `url` (string) — Адрес файла. У видео — страница плеера: YouTube, а иногда ВКонтакте.
  - `language` (string | null) — Язык надписей или звука, ISO 639-1. `null` — без языка или неизвестен.
  - `width`, `height` (integer | null) — Размер изображения в пикселях. У видео — `null`.
  - `youtube_id` (string | null) — ID ролика на YouTube. `null` у видео с других площадок — тогда открывайте `url`.
  - `preview_url` (string | null) — Обложка видео.
  - `runtime_sec` (integer | null) — Длительность видео в секундах.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестный `class`, `type` или `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 "type=poster" \
  --data-urlencode "language=ru" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/media"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "class": "image",
      "type": "poster",
      "url": "https://image.tmdb.org/t/p/original/piQXcdOGgv1O9HQ07pI0tnjkGJw.jpg",
      "language": "ru",
      "width": 2000,
      "height": 3000,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    },
    {
      "class": "image",
      "type": "poster",
      "url": "https://image.tmdb.org/t/p/original/7SivRwOLuA6DR09zNJ9JIo14GyX.jpg",
      "language": "ru",
      "width": 1000,
      "height": 1500,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 21
}
```

### Трейлер

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "class=video" \
  --data-urlencode "type=trailer" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/media"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "class": "video",
      "type": "trailer",
      "url": "https://www.youtube.com/watch?v=3lPxIA8DPQY",
      "language": null,
      "width": null,
      "height": null,
      "youtube_id": "3lPxIA8DPQY",
      "preview_url": "https://images.kinorium.com/movie/shot/472809/original_646484.jpg",
      "runtime_sec": 76
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 5
}
```

### Анимированный постер

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=poster_gif" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/media"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "class": "image",
      "type": "poster_gif",
      "url": "https://images.kinorium.com/movie/aniface/472809/original_1135344.mp4",
      "language": null,
      "width": null,
      "height": null,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}
```

### Разделы

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "group=class" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/media"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "class": "image",
      "has_more": true,
      "items": [
        {
          "class": "image",
          "type": "poster_gif",
          "url": "https://images.kinorium.com/movie/aniface/472809/original_1135344.mp4",
          "language": null,
          "width": null,
          "height": null,
          "youtube_id": null,
          "preview_url": null,
          "runtime_sec": null
        }
      ],
      "total": 423
    },
    {
      "class": "video",
      "has_more": true,
      "items": [
        {
          "class": "video",
          "type": "trailer",
          "url": "https://www.youtube.com/watch?v=3lPxIA8DPQY",
          "language": null,
          "width": null,
          "height": null,
          "youtube_id": "3lPxIA8DPQY",
          "preview_url": "https://images.kinorium.com/movie/shot/472809/original_646484.jpg",
          "runtime_sec": 76
        }
      ],
      "total": 62
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 2
}
```