Como obtenho a lista de elenco de uma série?

Chame GET /3/tv/{series_id}/credits e ordene o array cast por order. Os créditos de temporada cobrem uma só temporada, e os de episódio acrescentam guest_stars. O amodb não oferece créditos agregados de TV.

Como encontro o diretor de um filme?

Leia o array crew e escolha a entrada cujo job é Director. Um filme pode ter mais de um diretor, então colete todas as correspondências em vez de parar na primeira.

O que significa o campo order?

Order é a posição de um ator nos créditos, com 0 para o primeiro. Ordene cast por order para mostrar os papéis principais primeiro. As entradas de crew não têm order.

De onde vêm os atores convidados?

Só o endpoint de créditos de episódio retorna um array guest_stars, ao lado de crew. O array cast fica vazio. Os créditos de temporada e de série não listam os convidados separadamente.

API de créditos: elenco e equipe técnica no formato TMDB

Obter os créditos de um filme

GET /3/movie/{movie_id}/credits retorna dois arrays para um filme: cast, para quem aparece na tela, e crew, para quem trabalhou atrás das câmeras. Cada entrada traz o id da pessoa, então você pode abrir o registro completo na página de pessoas. Os mesmos dados estão disponíveis na resposta do filme com append_to_response=credits.

O exemplo lê Inception, imprime o diretor e lista os cinco primeiros atores dos créditos.

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)
	}
}

Parâmetros

movie_idcaminhoobrigatório
Id numérico do filme, por exemplo 27205.
api_keyconsultaum dos dois
Sua chave. Use este parâmetro ou o header Authorization: Bearer.
languageconsulta
Tag do TMDB como en-US ou fr-FR. Tags fora dos 14 idiomas base voltam para en.

Campos da resposta

Campo	Aplica-se a	Observações
`id`	nível superior	Id do filme, da série, da temporada ou do episódio a que os créditos pertencem.
`cast`, `crew`	nível superior	Arrays de entradas. Os créditos de episódio acrescentam `guest_stars`.
`id`	cada entrada	Id da pessoa. Abra-o com pessoas.
`name`, `original_name`	cada entrada	O nome da pessoa.
`known_for_department`	cada entrada	A principal função da pessoa no geral, não a função neste título.
`gender`, `popularity`, `adult`	cada entrada	Mesmo significado que no registro da pessoa.
`profile_path`	cada entrada	Caminho da imagem ou null. Acrescente a `https://img.amodb.dev/t/p/{size}`.
`credit_id`	cada entrada	String que identifica este crédito.
`character`	elenco, atores convidados	Nome do papel, vazio em algumas entradas.
`order`	elenco, atores convidados	Posição nos créditos, `0` é o primeiro.
`department`	equipe técnica	Grupo como `Directing`, `Writing`, `Production`, `Camera`, `Editing`, `Sound`, `Art`, `Visual Effects`, `Lighting`, `Costume & Make-Up` ou `Crew`.
`job`	equipe técnica	Função específica, por exemplo `Director`, `Screenplay` ou `Editor`.

Exemplo de resposta

GET /3/movie/27205/credits?language=en-US. A resposta tem hoje 52 entradas de elenco e 735 de equipe técnica, então os dois arrays foram cortados para duas aqui:

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"
    }
  ]
}

Créditos de séries, temporadas e episódios

Todos os caminhos abaixo usam a base https://api.amodb.dev/3 e aceitam language.

Método e caminho	Retorna
`GET /tv/{series_id}/credits`	Elenco e equipe técnica da série, com uma entrada por pessoa e papel.
`GET /tv/{series_id}/season/{season_number}/credits`	Elenco e equipe técnica de uma temporada.
`GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits`	`crew` e `guest_stars` de um episódio. `cast` é um array vazio.

Os mesmos dados estão disponíveis com append_to_response=credits nos caminhos de série, temporada e episódio. O formato das entradas é o mesmo dos créditos de filme acima. Os atores convidados de um episódio trazem character e order, e as entradas de equipe técnica trazem department e job.

GET /3/tv/1399/season/1/episode/1/credits?language=en-US, com os arrays cortados para duas entradas:

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"
    }
  ]
}

O amodb não oferece créditos agregados de TV nem busca por credit_id. Para o elenco de uma série, leia /tv/{series_id}/credits e ordene cast por order.

Ler elenco e equipe técnica em um app

Tarefa	Como
Mostrar o diretor	Escolha as entradas de `crew` com `job` igual a `Director`. Um filme pode ter vários.
Mostrar o elenco principal	Ordene `cast` por `order` e pegue os 10 primeiros.
Agrupar a equipe técnica	Agrupe por `department`. Uma pessoa com duas funções aparece duas vezes, então una pelo `id` da pessoa.
Mostrar o elenco de uma série	Leia os créditos da série e ordene `cast` por `order`.
Listar todos os departamentos e funções	Leia a lista de consulta descrita em gêneros e listas de consulta.

Erros

HTTP	status_code	Quando
401	7	A chave está ausente ou incorreta.
402	36	O período do plano terminou.
404	34	O filme, a série, a temporada ou o episódio não existe, ou o caminho não é oferecido.
405	37	Você chamou um método de escrita.
429	25	Acima do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`.

Os detalhes estão em erros e limites de requisições.

Notas práticas

Os créditos ficam em cache por 6 horas, como os detalhes. Um novo integrante do elenco pode levar esse tempo para aparecer.
Uma grande produção pode listar centenas de entradas de equipe técnica. Corte os arrays antes de renderizá-los.
profile_path é null para pessoas sem foto. Use w185 para linhas de lista e h632 para telas de detalhe.
Os registros de filmes e de TV estão em filmes e séries de TV. Os registros de temporadas e episódios estão em temporadas e episódios.