# Совместные работы

> Тайтлы, над которыми работали оба человека, и кем был в них каждый.

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

Запрос: `GET https://api.kinodata.space/v1.3/persons/{type}/{id}/with/{type2}/{id2}`

Каталоги у двух людей могут быть разными: `/persons/kp/37859/with/imdb/nm0634240` — это Леонардо ДиКаприо и Кристофер Нолан. У каждого тайтла — роли обоих: `credits_first` для первого человека в пути, `credits_second` для второго.

Роли задаются для каждого отдельно. `role_first=actor&role_second=director` у ДиКаприо и Нолана даёт ровно «Начало»: Кобб и режиссёр. `role` — роль, общая для обоих: `role=actor` — где они играли вместе, `role=self` — эфиры и церемонии, где оба были гостями. Чтобы убрать эфиры и хронику, исключите эти роли: из 20 общих тайтлов ДиКаприо и Нолана `role.not=self,archive` оставляет одно «Начало».

Список собирает движок каталога: работают все [фильтры и сортировки](https://kinodata.space/ru/docs/filters.md), пресеты, поиск по названию `q` и `fields`. Без `sort` — от новых работ к старым, `order=asc` — наоборот. В примере «Общие фильмы» ниже так собраны общие фильмы Киану Ривза и Лоренса Фишбёрна — по оценке IMDb, с ролями обоих. Те же тайтлы без ролей, но с курсором даёт каталог: `/titles?person=kp:37859&person=imdb:nm0634240`.

Если оба человека в пути — один и тот же, ответ `400` с подсказкой открыть фильмографию.

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

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

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

- `role_first` (csv) — Роль первого человека. Несколько через запятую — любая из них. `role_first.not` — убрать тайтлы, где у человека только такие роли.
  Значения: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Пример: `role_first=actor`.
- `role_second` (csv) — Роль второго человека. Несколько через запятую — любая из них. `role_second.not` — убрать тайтлы, где у человека только такие роли.
  Значения: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Пример: `role_second=director`.
- `role` (csv) — Роль, которая есть у обоих. Несколько через запятую — любая из них. `role.not` — убрать тайтлы, где хотя бы у одного из них только такие роли.
  Значения: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Пример: `role=actor`.
- `фильтры, q и sort` — Фильтры, поиск и сортировка каталога: `kind=movie`, `q=матрица`, `sort=-rating_imdb`. Подробно — в [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md).
  По умолчанию: `sort=-year`.
- `order` (enum) — Направление сортировки по умолчанию: `order=asc` — от старых работ к новым. Если задан `sort`, направление берётся из его знака.
  Значения: `asc`, `desc`.
  По умолчанию: `desc`. Пример: `order=asc`.
- `fields` (csv) — Какие поля элемента вернуть, как в [каталоге](https://kinodata.space/ru/docs/titles.md), плюс `credits_first` и `credits_second`. ID приходят всегда.
  Пример: `fields=title,year,credits_first,credits_second`.
- `lang` (ru | en) — Оставить в ответе один язык. Без него текстовые поля приходят парами `_ru` и `_en`. Подробнее — [Языки ответа](https://kinodata.space/ru/docs/languages.md).
  Пример: `lang=en`.
- `limit` (integer) — Сколько тайтлов вернуть, целое от 1 до 1000.
  По умолчанию: 1000. Пример: `limit=20`.
- `offset` (integer) — Сколько тайтлов пропустить, целое от 0.
  По умолчанию: 0.

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

- `items` (array) — Общие тайтлы — та же карточка, что в [каталоге](https://kinodata.space/ru/docs/titles.md), с ролями обоих людей.
  - `imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`, `kinorium_id` (string | null) — ID тайтла в каталогах. Приходят всегда, даже с `fields`.
  - `title_ru`, `title_en`, `title_original` (string | null) — Названия: на русском, на английском и на языке оригинала.
  - `year` (integer | null) — Год выхода.
  - `release_date` (string | null) — Первая дата выхода, `YYYY-MM-DD`.
  - `kind` (enum) — Вид тайтла: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Постер для русской и английской витрины.
  - `posters_by_source` (object) — Постер каждого источника: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd` (number | null) — Оценки Кинопоиска, TMDB, IMDb, Кинориума и Letterboxd, шкала 0–10.
  - `votes_kp`, `votes_tmdb`, `votes_imdb` (integer | null) — Голоса Кинопоиска, TMDB и IMDb.
  - `countries` (array) — Страны: `code`, `name_ru`, `name_en`.
  - `genres` (array) — Жанры: `slug`, `name_ru`, `name_en`.
  - `credits_first`, `credits_second` (array) — Роли первого и второго человека в этом тайтле — те же поля, что у роли в [фильмографии](https://kinodata.space/ru/docs/persons/filmography.md).
    - `role` (enum) — Роль. Подписи — в `/enums`, набор `credit_roles`.
    - `character_ru`, `character_en` (string | null) — Персонаж — у актёров и в дубляже, без пометок источника, как в [составе](https://kinodata.space/ru/docs/titles/cast.md). У `self` — кем человек появляется: «гость», «Guest».
    - `job_ru`, `job_en` (string | null) — Должность в съёмочной группе: «Исполнительный продюсер», «Executive Producer».
    - `ord` (integer | null) — Место в титрах: у актёров — порядок в титрах, у съёмочной группы — внутри своего цеха. `null` — место неизвестно: роль взята из фильмографии человека, а не из титров тайтла.
    - `sources` (array) — Какие каталоги подтвердили кредит: `kp`, `tmdb`, `kinorium`, всегда в этом порядке.
    - `uncredited` (boolean) — `true` — человека нет в титрах тайтла: источник пометил роль «в титрах не указан» или “uncredited”.
    - `disputed` (boolean) — `true` — кредит есть только у TMDB, а в составе тайтла на Кинопоиске или Кинориуме этого человека нет. В [составе тайтла](https://kinodata.space/ru/docs/titles/cast.md) такие кредиты не показываются; в списке работ скройте их условием `disputed`.
- `total` (integer | null) — Сколько общих тайтлов подходит под запрос. С поиском `q` — `null`.
- `limit`, `offset`, `has_more` — Пагинация — как в [любом списке](https://kinodata.space/ru/docs/lists.md#форма-списка).

## Ошибки

| статус | код | когда |
|---|---|---|
| 400 | `invalid_request` | В пути один и тот же человек; неизвестная роль, фильтр, ключ `sort` или поле в `fields`; `order` не `asc` и не `desc`; параметр другого эндпоинта (например, `relation` или `season`); `limit` меньше 1 или `offset` меньше 0; повторённый параметр; `cursor` — список листается `offset`. |
| 400 | `invalid_request` | Каталог не `imdb`, `kp`, `tmdb` или `kinorium` (у людей нет `tmdb_tv`); ID не в формате каталога — у IMDb это `nm` и цифры. |
| 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_first=actor" \
  --data-urlencode "role_second=director" \
  --data-urlencode "fields=title,year,credits_first,credits_second" \
  "https://api.kinodata.space/v1.3/persons/kp/37859/with/imdb/nm0634240"
```

Ответ `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "imdb_id": "tt1375666",
      "kp_id": "447301",
      "tmdb_id": "27205",
      "tmdb_tv_id": null,
      "kinorium_id": "472809",
      "title_ru": "Начало",
      "title_en": "Inception",
      "year": 2010,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Dom Cobb",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "director",
          "character_ru": null,
          "character_en": null,
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "writer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Сценарист",
          "job_en": "Writer",
          "ord": 13,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Продюсер",
          "job_en": "Producer",
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}
```

### Общие фильмы

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=movie" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb,credits_first,credits_second" \
  "https://api.kinodata.space/v1.3/persons/imdb/nm0000206/with/imdb/nm0000401"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_ru": "Матрица",
      "title_en": "The Matrix",
      "rating_imdb": 8.7,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Neo",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Morpheus",
          "job_ru": null,
          "job_en": null,
          "ord": 1,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt10366206",
      "kp_id": "1267348",
      "tmdb_id": "603692",
      "tmdb_tv_id": null,
      "kinorium_id": "2055679",
      "title_ru": "Джон Уик 4",
      "title_en": "John Wick: Chapter 4",
      "rating_imdb": 7.6,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "John Wick",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Исполнительный продюсер",
          "job_en": "Executive Producer",
          "ord": 3,
          "sources": [
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Bowery King",
          "job_ru": null,
          "job_en": null,
          "ord": 4,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt6146586",
      "kp_id": "1009536",
      "tmdb_id": "458156",
      "tmdb_tv_id": null,
      "kinorium_id": "1606958",
      "title_ru": "Джон Уик 3",
      "title_en": "John Wick: Chapter 3 – Parabellum",
      "rating_imdb": 7.4,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "John Wick",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Bowery King",
          "job_ru": null,
          "job_en": null,
          "ord": 3,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 7
}
```

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

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=movie" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb,credits_first,credits_second" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/persons/imdb/nm0000206/with/imdb/nm0000401"
```

Ответ `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_en": "The Matrix",
      "rating_imdb": 8.7,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "Neo",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Morpheus",
          "job_en": null,
          "ord": 1,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt10366206",
      "kp_id": "1267348",
      "tmdb_id": "603692",
      "tmdb_tv_id": null,
      "kinorium_id": "2055679",
      "title_en": "John Wick: Chapter 4",
      "rating_imdb": 7.6,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "John Wick",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_en": null,
          "job_en": "Executive Producer",
          "ord": 3,
          "sources": [
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Bowery King",
          "job_en": null,
          "ord": 4,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt6146586",
      "kp_id": "1009536",
      "tmdb_id": "458156",
      "tmdb_tv_id": null,
      "kinorium_id": "1606958",
      "title_en": "John Wick: Chapter 3 – Parabellum",
      "rating_imdb": 7.4,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "John Wick",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Bowery King",
          "job_en": null,
          "ord": 3,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 7
}
```

### Один человек дважды

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/persons/kp/41477/with/imdb/nm0634240"
```

Ответ `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "the path names the same person twice; a collaboration needs two people",
    "field": "id2",
    "hint": "for one person's work use /persons/:type/:id/filmography"
  }
}
```