Come ottengo il cast di una serie?

Chiama GET /3/tv/{series_id}/credits e ordina l'array cast per order. I crediti di stagione coprono una stagione, e i crediti di episodio aggiungono guest_stars. amodb non offre i crediti aggregati delle serie TV.

Come trovo il regista di un film?

Leggi l'array crew e scegli la voce in cui job è Director. Un film può avere più di un regista, quindi raccogli tutte le corrispondenze invece di fermarti alla prima.

Cosa significa il campo order?

Order è la posizione in locandina di un membro del cast, con 0 per il primo. Ordina cast per order per mostrare prima i ruoli principali. Le voci di crew non hanno order.

Da dove vengono gli ospiti speciali?

Solo l'endpoint dei crediti di episodio restituisce un array guest_stars, accanto a crew. Il suo array cast è vuoto. I crediti di stagione e di serie non elencano gli ospiti separatamente.

API crediti: endpoint di cast e troupe compatibili TMDB v3

Ottenere i crediti di un film

GET /3/movie/{movie_id}/credits restituisce due array per un film: cast per le persone che compaiono sullo schermo e crew per chi ha lavorato dietro la macchina da presa. Ogni voce contiene l'ID della persona, quindi puoi aprire la scheda completa nella pagina persone. Gli stessi dati sono disponibili nella risposta del film con append_to_response=credits.

L'esempio legge Inception, stampa il regista ed elenca i cinque attori in cima al cast.

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

Parametri

movie_idpercorsoobbligatorio
ID numerico del film, per esempio 27205.
api_keyqueryuno dei due
La tua chiave. Usa questa o l'header Authorization: Bearer.
languagequery
Tag TMDB come en-US o fr-FR. I tag fuori dalle 14 lingue di base ripiegano su en.

Campi della risposta

Campo	Si applica a	Note
`id`	livello principale	ID del film, della serie, della stagione o dell'episodio a cui appartengono i crediti.
`cast`, `crew`	livello principale	Array di voci. I crediti di episodio aggiungono `guest_stars`.
`id`	ogni voce	ID della persona. Aprila con persone.
`name`, `original_name`	ogni voce	Il nome della persona.
`known_for_department`	ogni voce	Il mestiere principale della persona in generale, non il mestiere in questo titolo.
`gender`, `popularity`, `adult`	ogni voce	Stesso significato della scheda della persona.
`profile_path`	ogni voce	Percorso dell'immagine o null. Da accodare a `https://img.amodb.dev/t/p/{size}`.
`credit_id`	ogni voce	Stringa che identifica questo singolo credito.
`character`	cast, ospiti speciali	Nome del ruolo, vuoto per alcune voci.
`order`	cast, ospiti speciali	Posizione in locandina, `0` è la prima.
`department`	crew	Gruppo come `Directing`, `Writing`, `Production`, `Camera`, `Editing`, `Sound`, `Art`, `Visual Effects`, `Lighting`, `Costume & Make-Up` o `Crew`.
`job`	crew	Mestiere specifico, per esempio `Director`, `Screenplay` o `Editor`.

Risposta di esempio

GET /3/movie/27205/credits?language=en-US. Oggi la risposta ha 52 voci di cast e 735 di troupe, quindi qui entrambi gli array sono ridotti a due:

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

Crediti di serie, stagioni ed episodi

Tutti i percorsi qui sotto condividono la base https://api.amodb.dev/3 e accettano language.

Metodo e percorso	Restituisce
`GET /tv/{series_id}/credits`	Cast e troupe della serie, una voce per persona e ruolo.
`GET /tv/{series_id}/season/{season_number}/credits`	Cast e troupe di una stagione.
`GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits`	`crew` e `guest_stars` di un episodio. `cast` è un array vuoto.

Gli stessi dati sono disponibili con append_to_response=credits sui percorsi di serie, stagione ed episodio. La struttura delle voci corrisponde ai crediti dei film qui sopra. Gli ospiti speciali di un episodio portano character e order, e le voci della troupe portano department e job.

GET /3/tv/1399/season/1/episode/1/credits?language=en-US, con gli array ridotti a due voci:

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 non offre i crediti aggregati delle serie TV né la ricerca per credit_id. Per il cast di una serie leggi /tv/{series_id}/credits e ordina cast per order.

Leggere cast e troupe in un'app

Compito	Come
Mostrare il regista	Scegliere le voci di `crew` con `job` uguale a `Director`. Un film può averne diversi.
Mostrare il cast principale	Ordinare `cast` per `order` e prendere i primi 10.
Raggruppare la troupe	Raggruppare per `department`. Una persona con due mestieri compare due volte, quindi unisci sull'`id` della persona.
Mostrare il cast di una serie	Leggere i crediti della serie e ordinare `cast` per `order`.
Elencare tutti i reparti e mestieri	Leggere la lista di riferimento descritta in generi e liste di riferimento.

Errori

HTTP	status_code	Quando
401	7	La chiave manca o è sbagliata.
402	36	Il periodo del piano è terminato.
404	34	Il film, la serie, la stagione o l'episodio non esiste, oppure il percorso non è offerto.
405	37	Hai chiamato un metodo di scrittura.
429	25	Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`.

I dettagli sono nelle pagine errori e limiti di richieste.

Note pratiche

I crediti restano in cache per 6 ore, come i dettagli. Un nuovo membro del cast può impiegare quel tempo a comparire.
Una grande produzione può elencare centinaia di voci di troupe. Taglia gli array prima di mostrarli.
profile_path è null per le persone senza foto. Usa w185 per le righe degli elenchi e h632 per le viste di dettaglio.
Le schede di film e serie sono in film e serie TV. Le schede di stagioni ed episodi sono in stagioni ed episodi.