# Состав

> Актёры, дубляж и съёмочная группа тайтла, сведённые из Кинопоиска, TMDB и Кинориума.

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

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

Без параметров состав приходит разделами по ролям — режиссёры, актёры, сценаристы, продюсеры и дальше, по 10 человек в каждом. Чтобы получить всех людей одной роли, сузьте список: `role=actor` даёт плоский список с пагинацией.

`roles` описывает весь состав, а не страницу: сколько людей в каждой роли и подписи ролей. По нему рисуются вкладки, и они не меняются, пока вы листаете.

Дубляж — отдельная роль `voice`: актёр дубляжа, персонаж, которого он озвучил, и в `dubs` — актёр оригинала. Люди, которые появляются в роли себя — в ток-шоу, церемониях, документальном кино, — роль `self`, архивные кадры — `archive`.

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

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

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

- `role` (csv) — Оставить роли, через запятую. Список становится плоским, его можно листать: `role=director,writer` — режиссёры и сценаристы одним списком. `role.not` — убрать роли и оставить остальные: `role.not=self,archive` — состав без эфиров и хроники. Разделы при этом остаются, плоский список — с `group=none`.
  Значения: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Пример: `role=director,writer`.
- `source` (enum) — Оставить кредиты, которые подтвердил этот каталог.
  Значения: `kp`, `tmdb`, `kinorium`.
  Пример: `source=kp`.
- `group` (enum) — Разбить список на разделы. `none` — плоский список. Как устроены разделы — в [Списки и пагинация](https://kinodata.space/ru/docs/lists.md#разделы).
  Значения: `role`, `none`.
  По умолчанию: `role`.
- `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.

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

- `roles` (array) — Сколько людей во всём составе по ролям: `role`, подписи `label_ru` и `label_en`, `count`. Порядок — как в титрах: режиссёры, актёры, в роли себя, архивные кадры, сценаристы, продюсеры и дальше.
- `items` (array) — Разделы по ролям — у каждого `role`, подписи, `total`, `has_more` и `items`. В плоском списке — сами кредиты.
  - `person` (object) — Человек. По любому его ID открывается [карточка](https://kinodata.space/ru/docs/persons/card.md) и [фильмография](https://kinodata.space/ru/docs/persons/filmography.md).
    - `imdb_id`, `kp_id`, `tmdb_id`, `kinorium_id` (string | null) — ID человека в каталогах.
    - `name_ru`, `name_en` (string | null) — Имя на русском и на английском.
    - `name_original` (string | null) — Имя на родном языке, если он пишется не латиницей и не кириллицей.
    - `birth_year`, `death_year` (integer | null) — Годы рождения и смерти.
    - `gender` (enum | null) — Пол: `male` или `female`.
    - `photo_url` (string | null) — Портрет — одно из `photos_by_source`: первое, что есть, в порядке TMDB, Кинориум, Кинопоиск. Как в [карточке человека](https://kinodata.space/ru/docs/persons/card.md).
    - `photos_by_source` (object) — Фото каждого источника: `kp`, `tmdb`, `kinorium`. Снимки TMDB в составе — 185 px шириной (`/t/p/w185/`); крупнее — замените этот сегмент ссылки на `h632` или `original`.
    - `professions` (array) — Профессии, как их перечисляют источники, — значения из набора `credit_roles`.
  - `role` (enum) — Роль в этом тайтле. Подписи — в `/enums`, набор `credit_roles`.
  - `character_ru`, `character_en` (string | null) — Персонаж — у актёров и в дубляже. Пометок источника в нём нет: «в титрах не указан» — это `uncredited`, а «играет самого себя» и «хроника» уже сказаны ролью `self` или `archive`. Имя, которое источник не перевёл, приходит в `character_en`.
  - `character_original` (string | null) — Имя персонажа на языке оригинала, если он не русский и не английский.
  - `character_photo_url` (string | null) — Кадр с этим персонажем.
  - `job_ru`, `job_en` (string | null) — Должность в съёмочной группе. `job_en` — как её пишет TMDB, `job_ru` — перевод: «Director of Photography» → «Оператор-постановщик». У редких должностей перевода нет — `job_ru` равен `null`.
  - `dubs` (object | null) — В дубляже — кого озвучил актёр: его ID (`imdb_id`, `kp_id`, `tmdb_id`, `kinorium_id`) и имя (`name_ru`, `name_en`).
  - `ord` (integer | null) — Место в титрах: у актёров — порядок в титрах, у съёмочной группы — внутри своего цеха. `null` — место неизвестно: роль взята из фильмографии человека, а не из титров тайтла.
  - `uncredited` (boolean) — `true` — человека нет в титрах тайтла: источник пометил роль «в титрах не указан» или “uncredited”.
  - `sources` (array) — Какие каталоги подтвердили кредит: `kp`, `tmdb`, `kinorium`. Два и больше значат, что человек сведён по совпадению, а не угадан. Порядок всегда один: `kp`, `tmdb`, `kinorium`. Кредита, который есть только у TMDB, когда состав тайтла есть у Кинопоиска или Кинориума и этого человека в нём нет, в составе нет.
- `total`, `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | Неизвестная роль в `role` или `role.not`, неизвестный `source` или `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 "role=director" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "person": {
        "imdb_id": "nm0634240",
        "kp_id": "41477",
        "tmdb_id": "525",
        "kinorium_id": "476400",
        "name_ru": "Кристофер Нолан",
        "name_en": "Christopher Nolan",
        "name_original": null,
        "birth_year": 1970,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_41477.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/476400.jpg?20260829201207"
        },
        "professions": [
          "actor",
          "cinematographer",
          "composer",
          "director",
          "editor",
          "producer",
          "writer",
          "author"
        ]
      },
      "role": "director",
      "character_ru": null,
      "character_en": null,
      "character_original": null,
      "character_photo_url": null,
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "kinorium"
      ]
    }
  ],
  "limit": 1000,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 1
}
```

### Актёры

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role=actor" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm0000138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "kinorium_id": "138",
        "name_ru": "Леонардо ДиКаприо",
        "name_en": "Leonardo DiCaprio",
        "name_original": null,
        "birth_year": 1974,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_37859.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/138.jpg?20201106112423"
        },
        "professions": [
          "actor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_ru": "Кобб",
      "character_en": "Dom Cobb",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_138.jpg?1614892697",
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    },
    {
      "person": {
        "imdb_id": "nm0330687",
        "kp_id": "9867",
        "tmdb_id": "24045",
        "kinorium_id": "249949",
        "name_ru": "Джозеф Гордон-Левитт",
        "name_en": "Joseph Gordon-Levitt",
        "name_original": null,
        "birth_year": 1981,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_9867.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/249949.jpg?20220127123554"
        },
        "professions": [
          "actor",
          "composer",
          "director",
          "editor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_ru": "Артур",
      "character_en": "Arthur",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_249949.jpg?1614363858",
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    }
  ],
  "limit": 2,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 87
}
```

### Дубляж

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

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm2511538",
        "kp_id": "1193331",
        "tmdb_id": "932353",
        "kinorium_id": "1570811",
        "name_ru": "Сергей Бурунов",
        "name_en": "Sergey Burunov",
        "name_original": null,
        "birth_year": 1977,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/c2pbTB0BomzUMZPbTKTZ8wa7byW.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_1193331.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/c2pbTB0BomzUMZPbTKTZ8wa7byW.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/1570811.jpg?20241003124819"
        },
        "professions": [
          "actor",
          "voice"
        ]
      },
      "role": "voice",
      "character_ru": "Кобб",
      "character_en": "Cobb",
      "character_original": null,
      "character_photo_url": null,
      "job_ru": null,
      "job_en": null,
      "dubs": {
        "kinorium_id": "138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "imdb_id": "nm0000138",
        "name_ru": "Леонардо ДиКаприо",
        "name_en": "Leonardo DiCaprio"
      },
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "kinorium"
      ]
    }
  ],
  "limit": 1,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 16
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role=actor" \
  --data-urlencode "limit=2" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm0000138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "kinorium_id": "138",
        "name_en": "Leonardo DiCaprio",
        "name_original": null,
        "birth_year": 1974,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_37859.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/138.jpg?20201106112423"
        },
        "professions": [
          "actor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_en": "Dom Cobb",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_138.jpg?1614892697",
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    },
    {
      "person": {
        "imdb_id": "nm0330687",
        "kp_id": "9867",
        "tmdb_id": "24045",
        "kinorium_id": "249949",
        "name_en": "Joseph Gordon-Levitt",
        "name_original": null,
        "birth_year": 1981,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_9867.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/249949.jpg?20220127123554"
        },
        "professions": [
          "actor",
          "composer",
          "director",
          "editor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_en": "Arthur",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_249949.jpg?1614363858",
      "job_en": null,
      "dubs": null,
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    }
  ],
  "limit": 2,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 87
}
```