Как получить список актеров сериала?

Вызовите GET /3/tv/{series_id}/credits и отсортируйте массив cast по order. Credits сезона охватывают один сезон, а credits серии добавляют guest_stars. Сводных credits сериалов amodb не предоставляет.

Как найти режиссера фильма?

Прочитайте массив crew и выберите запись, у которой job равен Director. У фильма может быть несколько режиссеров, поэтому собирайте все совпадения, а не останавливайтесь на первом.

Что означает поле order?

Order это позиция актера в титрах, где 0 означает первого в списке. Отсортируйте cast по order, чтобы показать главные роли первыми. У записей crew поля order нет.

Откуда берутся приглашенные звезды?

Массив guest_stars возвращает только эндпоинт credits серии, рядом с crew. Его массив cast пуст. Credits сезона и сериала приглашенных звезд отдельно не перечисляют.

API актеров и съемочной группы: эндпоинты credits TMDB v3

Получение актеров и съемочной группы фильма

GET /3/movie/{movie_id}/credits возвращает два массива для одного фильма: cast для тех, кто появляется на экране, и crew для тех, кто работал за кадром. В каждой записи есть ID персоны, поэтому полную запись можно открыть на странице люди. Те же данные доступны внутри ответа о фильме через append_to_response=credits.

Пример читает фильм Inception, выводит режиссера и пять первых актеров по порядку в титрах.

curl JavaScript Python PHP Go

bashjspyphpgo

curl -sSf "https://api.amodb.dev/3/movie/27205/credits?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const credits = await res.json();
const director = credits.crew.find((c) => c.job === 'Director');
console.log('Director:', director?.name);
for (const c of [...credits.cast].sort((a, b) => a.order - b.order).slice(0, 5)) {
  console.log(c.order, c.name, 'as', c.character);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/27205/credits",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
credits = r.json()
director = next((c for c in credits["crew"] if c["job"] == "Director"), None)
print("Director:", director and director["name"])
for c in sorted(credits["cast"], key=lambda c: c["order"])[:5]:
    print(c["order"], c["name"], "as", c["character"])

<?php
$url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$credits = json_decode($body, true);
usort($credits['cast'], fn ($a, $b) => $a['order'] <=> $b['order']);
foreach (array_slice($credits['cast'], 0, 5) as $c) {
    echo $c['order'], ' ', $c['name'], ' as ', $c['character'], PHP_EOL;
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Credits struct {
	Cast []struct {
		Order     int    `json:"order"`
		Name      string `json:"name"`
		Character string `json:"character"`
	} `json:"cast"`
	Crew []struct {
		Name string `json:"name"`
		Job  string `json:"job"`
	} `json:"crew"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/27205/credits?language=en-US", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var c Credits
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	for _, m := range c.Crew {
		if m.Job == "Director" {
			fmt.Println("Director:", m.Name)
		}
	}
	for i, a := range c.Cast {
		if i == 5 {
			break
		}
		fmt.Println(a.Order, a.Name, "as", a.Character)
	}
}

Параметры

movie_idпутьобязателен
Числовой ID фильма, например 27205.
api_keyстрока запросаодин из двух
Ваш ключ. Используйте его или заголовок Authorization: Bearer.
languageстрока запроса
Тег TMDB, например en-US или fr-FR. Теги вне 14 базовых языков заменяются на en.

Поля ответа

Поле	Где применяется	Примечания
`id`	верхний уровень	ID фильма, сериала, сезона или серии, к которым относятся credits.
`cast`, `crew`	верхний уровень	Массивы записей. Credits серии добавляют `guest_stars`.
`id`	каждая запись	ID персоны. Откройте его на странице люди.
`name`, `original_name`	каждая запись	Имя персоны.
`known_for_department`	каждая запись	Основная профессия персоны в целом, а не ее работа в этом проекте.
`gender`, `popularity`, `adult`	каждая запись	Значение такое же, как в записи персоны.
`profile_path`	каждая запись	Путь к изображению или null. Добавьте к `https://img.amodb.dev/t/p/{size}`.
`credit_id`	каждая запись	Строка, которая идентифицирует эту конкретную запись.
`character`	актеры, приглашенные звезды	Название роли, у некоторых записей пустое.
`order`	актеры, приглашенные звезды	Позиция в титрах, `0` означает первую.
`department`	съемочная группа	Отдел, например `Directing`, `Writing`, `Production`, `Camera`, `Editing`, `Sound`, `Art`, `Visual Effects`, `Lighting`, `Costume & Make-Up` или `Crew`.
`job`	съемочная группа	Конкретная должность, например `Director`, `Screenplay` или `Editor`.

Пример ответа

GET /3/movie/27205/credits?language=en-US. Сейчас в ответе 52 записи cast и 735 записей crew, поэтому здесь оба массива сокращены до двух:

JSON

{
  "id": 27205,
  "cast": [
    {
      "adult": false,
      "gender": 2,
      "id": 6193,
      "known_for_department": "Acting",
      "name": "Leonardo DiCaprio",
      "original_name": "Leonardo DiCaprio",
      "popularity": 9.3213,
      "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
      "character": "Dom Cobb",
      "credit_id": "52fe4534c3a368484e04de03",
      "order": 0
    },
    {
      "adult": false,
      "gender": 2,
      "id": 24045,
      "known_for_department": "Acting",
      "name": "Joseph Gordon-Levitt",
      "original_name": "Joseph Gordon-Levitt",
      "popularity": 5.6202,
      "profile_path": "/z2FA8js799xqtfiFjBTicFYdfk.jpg",
      "character": "Arthur",
      "credit_id": "52fe4534c3a368484e04de0b",
      "order": 1
    }
  ],
  "crew": [
    {
      "adult": false,
      "gender": 2,
      "id": 1025090,
      "known_for_department": "Crew",
      "name": "Jim Wilkey",
      "original_name": "Jim Wilkey",
      "popularity": 0.9114,
      "profile_path": "/peEdS7ZYHwEeMJAwInJj732AeYs.jpg",
      "credit_id": "6634553bad59b501286dab5f",
      "department": "Crew",
      "job": "Stunt Driver"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1741194,
      "known_for_department": "Sound",
      "name": "James Thatcher",
      "original_name": "James Thatcher",
      "popularity": 0.6215,
      "profile_path": null,
      "credit_id": "5bcdece8925141613e0216d3",
      "department": "Sound",
      "job": "Musician"
    }
  ]
}

Credits сериалов, сезонов и серий

Все пути ниже используют базовый URL https://api.amodb.dev/3 и принимают language.

Метод и путь	Что возвращает
`GET /tv/{series_id}/credits`	Актерский состав и съемочная группа сериала, одна запись на каждую персону и роль.
`GET /tv/{series_id}/season/{season_number}/credits`	Актерский состав и съемочная группа одного сезона.
`GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits`	`crew` и `guest_stars` одной серии. `cast` это пустой массив.

Те же данные доступны через append_to_response=credits на путях сериала, сезона и серии. Структура записи совпадает с credits фильма выше. Приглашенные звезды серии содержат character и order, а записи съемочной группы содержат department и job.

GET /3/tv/1399/season/1/episode/1/credits?language=en-US, массивы сокращены до двух записей:

JSON

{
  "id": 63056,
  "cast": [],
  "crew": [
    {
      "department": "Writing",
      "job": "Writer",
      "credit_id": "5256c8a019c2956ff6046e2b",
      "adult": false,
      "gender": 2,
      "id": 9813,
      "known_for_department": "Writing",
      "name": "David Benioff",
      "original_name": "David Benioff",
      "popularity": 2.0354,
      "profile_path": "/xvNN5huL0X8yJ7h3IZfGG4O2zBD.jpg"
    },
    {
      "department": "Editing",
      "job": "Editor",
      "credit_id": "54eef2ab925141795f005d4f",
      "adult": false,
      "gender": 2,
      "id": 18077,
      "known_for_department": "Editing",
      "name": "Oral Norrie Ottey",
      "original_name": "Oral Norrie Ottey",
      "popularity": 0,
      "profile_path": null
    }
  ],
  "guest_stars": [
    {
      "character": "Benjen Stark",
      "credit_id": "5256c8b919c2956ff604836a",
      "order": 61,
      "adult": false,
      "gender": 2,
      "id": 119783,
      "known_for_department": "Acting",
      "name": "Joseph Mawle",
      "original_name": "Joseph Mawle",
      "popularity": 1.4645,
      "profile_path": "/1Ocb9v3h54beGVoJMm4w50UQhLf.jpg"
    },
    {
      "character": "Rickon Stark",
      "credit_id": "566a83bcc3a3683f56003604",
      "order": 80,
      "adult": false,
      "gender": 2,
      "id": 1050248,
      "known_for_department": "Acting",
      "name": "Art Parkinson",
      "original_name": "Art Parkinson",
      "popularity": 1.2594,
      "profile_path": "/ejAKOJME1DsvHECLWdQ7dEtXyyc.jpg"
    }
  ]
}

amodb не предоставляет сводные credits сериалов и поиск по credit_id. Чтобы получить актерский состав сериала, читайте /tv/{series_id}/credits и сортируйте cast по order.

Как использовать актеров и съемочную группу в приложении

Задача	Как
Показать режиссера	Выберите записи `crew`, у которых `job` равно `Director`. У фильма их может быть несколько.
Показать главных актеров	Отсортируйте `cast` по `order` и возьмите первые 10.
Сгруппировать съемочную группу	Сгруппируйте по `department`. Персона с двумя должностями встречается дважды, поэтому объединяйте записи по `id` персоны.
Показать актеров сериала	Прочитайте credits сериала и отсортируйте `cast` по `order`.
Получить все отделы и должности	Прочитайте справочник, описанный на странице жанры и справочники.

Ошибки

HTTP	status_code	Когда
401	7	Ключ отсутствует или неверен.
402	36	Срок действия тарифа закончился.
404	34	Фильма, сериала, сезона или серии не существует, либо такой путь не предоставляется.
405	37	Вы вызвали метод записи.
429	25	Превышен лимит запросов в минуту. Подождите столько секунд, сколько указано в `Retry-After`.

Подробности смотрите на страницах ошибки и лимиты запросов.

Практические замечания

Credits кэшируются на 6 часов, как и сведения о проекте. Новый актер может появиться только спустя это время.
У крупной постановки в crew могут быть сотни записей. Обрежьте массивы перед отрисовкой.
profile_path равен null у персон без фото. Используйте w185 для строк списка и h632 для страниц с подробностями.
Записи фильмов и сериалов описаны на страницах фильмы и сериалы. Записи сезонов и серий описаны на странице сезоны и серии.