# Media

> A title’s posters, stills, logos and videos in one list.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

Request: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/media`

Images and videos share one shape. An image has empty `youtube_id`, `preview_url` and `runtime_sec`; a video has empty `width` and `height`. URLs are complete: no need to build a link from parts.

A media library can be large: *Inception* has 485 files. Narrow it down: `type=poster&language=en` for English posters, `class=video` for videos only, `group=type` for sections with their sizes.

The animated poster, `poster_gif`, is listed as an image but is an mp4 clip of up to 7 MB. Show it in `<video autoplay muted loop playsinline>` and load it on demand. When there is one, there is only one, and it comes first.

## Path parameters

- `type` (string, required) — The catalog the ID comes from: IMDb, Kinopoisk, TMDB (movie or series) or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, required) — The ID in that catalog. IMDb IDs are `tt` followed by digits (`tt1375666`); the others are digits (`447301`).

## Query parameters

- `class` (enum) — Images only or videos only.
  Values: `image`, `video`.
  Default: both.
- `type` (enum) — File type. Images: `poster_gif`, `poster`, `backdrop`, `still`, `cover`, `logo`, `promo`, `backstage`, `other`. Videos: `trailer`, `teaser`, `tvspot`, `clip`, `interview`, `music_video`, `behind_scenes`, `blooper`, `overview`, `other`. Both have `other`: add `class` to pick one. Labels are in `/enums`, sets `image_types` and `video_kinds`.
  Default: all. Example: `type=poster`.
- `language` (string) — The language of the lettering on an image or the audio of a video, an ISO 639-1 code.
  Default: all. Example: `language=ru`.
- `group` (enum) — Split the list into sections. `none` gives a flat list. How sections work is in [Lists and pagination](https://kinodata.space/en/docs/lists.md#sections).
  Values: `type`, `class`, `language`, `none`.
  Default: no sections.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).
  Example: `lang=en`.
- `limit` (integer) — How many items to return, a whole number from 1. With sections, per section, up to 50. In a flat list, up to 1000. Above the cap isn’t an error: the API lowers it and shows the value in `limit`.
  Default: 10 per section, 1000 in a flat list. Example: `limit=20`.
- `offset` (integer) — How many items to skip, a whole number from 0. Only in a flat list: with sections it returns `400`.
  Default: 0.

## Response fields

- `items` (array) — Files. With `group`, sections with their own `total` and labels.
  - `class` (enum) — `image` or `video`.
  - `type` (enum) — File type.
    Values: `poster_gif`, `poster`, `backdrop`, `still`, `cover`, `logo`, `promo`, `backstage`, `other`, `trailer`, `teaser`, `tvspot`, `clip`, `interview`, `music_video`, `behind_scenes`, `blooper`, `overview`.
  - `url` (string) — File URL. For a video, the player page: YouTube, sometimes VK.
  - `language` (string | null) — Language of the lettering or audio, ISO 639-1. `null` means no language or unknown.
  - `width`, `height` (integer | null) — Image size in pixels. `null` for a video.
  - `youtube_id` (string | null) — The YouTube video ID. `null` for videos hosted elsewhere; open `url` then.
  - `preview_url` (string | null) — Video cover image.
  - `runtime_sec` (integer | null) — Video length in seconds.
- `total`, `limit`, `offset`, `has_more` — Paging, as in [every list](https://kinodata.space/en/docs/lists.md#the-shape-of-a-list).

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | An unknown `class`, `type` or `group`; `offset` together with sections; a parameter this list doesn’t understand (such as `sort` or `fields`); the response lists the allowed ones. |
| 404 | `not_found` | No title found for this ID. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English posters

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

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "class": "image",
      "type": "poster",
      "url": "https://image.tmdb.org/t/p/original/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
      "language": "en",
      "width": 2000,
      "height": 3000,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    },
    {
      "class": "image",
      "type": "poster",
      "url": "https://images.kinorium.com/movie/poster/472809/w1500_52292781.jpg",
      "language": "en",
      "width": 1500,
      "height": 2222,
      "youtube_id": null,
      "preview_url": null,
      "runtime_sec": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 114
}
```

### Trailer

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

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

### Animated poster

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

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

### Sections

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

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