# API de temporadas e episódios de séries > Leia uma temporada com todos os episódios em GET /3/tv/{series_id}/season/{season_number}, ou um único episódio um nível abaixo. O JSON segue o TMDB v3, com air_date, episode_number, runtime e still_path. Cada episódio traz crew e guest_stars, a temporada 0 guarda os especiais, e append_to_response acrescenta credits, images e videos. ## Endpoint `GET /3/tv/{series_id}/season/{season_number}` ```bash curl "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to team up with a former student and create a top of the line crystal meth in a used RV, to provide for his family once he is gone.", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7029219c29533d00dd2c1", "adult": false, "gender": 2, "id": 2483, "known_for_department": "Camera", "name": "约翰·托尔", "original_name": "约翰·托尔", "popularity": 1.1957, "profile_path": "/cfL9A6tC7L5Ps5fq1o3WpVKGMb1.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee313280006e8", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Jock", "credit_id": "52542275760ee313280006b4", "order": 500, "adult": false, "gender": 2, "id": 1216132, "known_for_department": "Acting", "name": "Aaron Hill", "original_name": "Aaron Hill", "popularity": 1.6521, "profile_path": "/rNp31SeoVqSQU6OZWxZUhGwAgyq.jpg" }, { "character": "Dr. Belknap", "credit_id": "52725cb1760ee3044d0b9984", "order": 502, "adult": false, "gender": 2, "id": 161591, "known_for_department": "Acting", "name": "Gregory Chase", "original_name": "Gregory Chase", "popularity": 0.5435, "profile_path": "/gNdodev00CROpXuAh5EFmkWTVOo.jpg" } ] }, { "air_date": "2008-01-27", "episode_number": 2, "episode_type": "standard", "id": 62086, "name": "Cat's in the Bag...", "overview": "Walt and Jesse attempt to tie up loose ends. The desperate situation gets more complicated with the flip of a coin. Walt's wife, Skyler, becomes suspicious of Walt's strange behavior.", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/AbMoecO0ZZio0LcgeLxlzdyGs6X.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Ob-Gyn", "credit_id": "63012c9c5f4b73008267ba53", "order": 682, "adult": false, "gender": 0, "id": 1448105, "known_for_department": "Acting", "name": "Shane Marinson", "original_name": "Shane Marinson", "popularity": 0, "profile_path": null }, { "character": "Ben", "credit_id": "63012d2111c066007cbc37b1", "order": 683, "adult": false, "gender": 0, "id": 3670897, "known_for_department": "Acting", "name": "Jason Byrd", "original_name": "Jason Byrd", "popularity": 0, "profile_path": null } ] }, { "air_date": "2008-02-10", "episode_number": 3, "episode_type": "standard", "id": 62087, "name": "...And the Bag's in the River", "overview": "Walter fights with Jesse over his drug use, causing him to leave Walter alone with their captive, Krazy-8. Meanwhile, Hank has a scared straight moment with Walter Jr. after his aunt discovers he has been smoking pot. Also, Skylar is upset...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/2kBeBlxGqBOdWlKwzAxiwkfU5on.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Carmen Molina", "credit_id": "52542273760ee31328000676", "order": 643, "adult": false, "gender": 1, "id": 115688, "known_for_department": "Acting", "name": "卡门·塞兰诺", "original_name": "卡门·塞兰诺", "popularity": 1.1342, "profile_path": "/nzJEe2UqvvMIBJZP1aeFEj4EunN.jpg" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Obter uma temporada `GET /3/tv/{series_id}/season/{season_number}` retorna uma temporada e o array `episodes` completo em uma só resposta. Os números de temporada começam em `1`, e `0` é reservado aos especiais. Pegue o id da série e os números das temporadas no registro de [séries de TV](https://amodb.dev/pt/tv-series/). O exemplo lê a temporada 1 de Breaking Bad. O código imprime uma linha por episódio. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/tv/1396/season/1?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 season = await res.json(); for (const ep of season.episodes) { console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396/season/1", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() season = r.json() for ep in season["episodes"]: print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?") ``` ```php 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"); } $season = json_decode($body, true); foreach ($season['episodes'] as $ep) { printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Season struct { Name string `json:"name"` Episodes []struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` } `json:"episodes"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?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 s Season if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } for _, e := range s.Episodes { fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime) } } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | -------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- | | `series_id` | caminho | sim | Id numérico da série, por exemplo `1396`. | | `season_number` | caminho | sim | Número inteiro da temporada. `0` retorna os especiais. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | | `language` | consulta | não | Tag do TMDB como `en-US` ou `fr-FR`. 14 idiomas base são atendidos. Padrão `en-US`. | | `append_to_response` | consulta | não | Valores no nível da temporada: `credits`, `external_ids`, `images`, `videos`. Outros nomes são ignorados. | ### Campos da resposta | Campo | Tipo | Observações | | --------------------- | -------------- | ------------------------------------------------------------ | | `id`, `season_number` | inteiro | Id da temporada e o número dela dentro da série. | | `name`, `overview` | string | Texto localizado, vazio quando não existe tradução. | | `air_date` | string ou null | Data do primeiro episódio, `YYYY-MM-DD`. | | `poster_path` | string ou null | Acrescente a `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | número | Nota agregada dos usuários para a temporada. | | `episodes` | array | Todos os episódios, com os campos listados na próxima seção. | ### Exemplo de resposta `GET /3/tv/1396/season/1?language=en-US`. A temporada tem 7 episódios, então `episodes` foi cortado para uma entrada, e os arrays `crew` e `guest_stars` dessa entrada ficaram de fora: ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0 } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` Todo episódio na resposta da temporada também traz os arrays `crew` e `guest_stars`, com o formato de entrada descrito em [créditos](https://amodb.dev/pt/credits/). `runtime` pode ser null em um episódio ainda não exibido. ## Obter um episódio `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` retorna um episódio. A resposta da temporada já traz todos os episódios com `crew` e `guest_stars`, então use este endpoint para atualizar um registro sem recarregar a temporada. Ele aceita `language` e `append_to_response` com `credits`, `external_ids`, `images`, `translations` e `videos`. Uma requisição como `/3/tv/1396/season/1/episode/1?append_to_response=credits` custa uma requisição. | Campo | Tipo | Observações | | --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | inteiro | Id do episódio. | | `show_id` | inteiro | Id da série. Presente na resposta da temporada e nos ponteiros da série, mas não na resposta de um único episódio. | | `season_number`, `episode_number` | inteiro | Posição dentro da série. Use-os para montar o caminho da requisição. | | `name`, `overview` | string | Texto localizado. | | `air_date` | string ou null | Só a data, sem hora nem fuso horário. Null quando não há agenda. | | `episode_type` | string | `standard` para episódios comuns. Para identificar um final, compare `episode_number` com o `episode_count` dessa temporada no registro da série. | | `runtime` | inteiro ou null | Minutos. | | `production_code` | string | Código do estúdio, muitas vezes vazio. | | `still_path` | string ou null | Still do episódio. Use `w300` ou `original` de `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | número, inteiro | Nota agregada dos usuários. | | `crew`, `guest_stars` | array | Créditos deste episódio, veja [créditos](https://amodb.dev/pt/credits/). | ## Próximo e último episódio no registro da série O endpoint da série retorna `next_episode_to_air` e `last_episode_to_air`. Cada um é um resumo de episódio com os campos acima, mais `show_id` e sem `crew` e `guest_stars`. O próximo é null para séries encerradas e para séries em andamento sem data confirmada. O exemplo lê South Park, uma série em andamento. ```js const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const next = (await res.json()).next_episode_to_air; console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode'); ``` Para uma contagem regressiva, compare `air_date` com a data local do espectador. O valor não traz hora do dia, então mostre uma data e não um horário. ## Subrecursos de temporada e de episódio Os caminhos de temporada e de episódio têm seus próprios subrecursos. Vários deles retornam dados vazios hoje. | Método e caminho | Retorna | | --------------------------------------------------------- | ------------------------------------------------------------ | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` e `crew` da temporada | | `GET /tv/{series_id}/season/{season_number}/images` | `id` e um array `posters` vazio | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` e um array `results` vazio | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` mais `tvdb_id`, `wikidata_id` e outros ids, todos null | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` e um array `translations` vazio | | `GET .../episode/{episode_number}/credits` | `id`, um `cast` vazio, `crew` e `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` e um array `stills` com o still do episódio | | `GET .../episode/{episode_number}/videos` | `id` e um array `results` vazio | | `GET .../episode/{episode_number}/external_ids` | `id` mais `imdb_id`, `tvdb_id` e outros ids, todos null | | `GET .../episode/{episode_number}/translations` | `id` e um array `translations` com nome e sinopse por idioma | Os créditos de temporada e de episódio estão em [créditos](https://amodb.dev/pt/credits/), e os stills em [imagens](https://amodb.dev/pt/images-api/). O amodb não oferece os caminhos `changes` do TMDB nem um endpoint para os episódios de um grupo de episódios. ## Erros | HTTP | status_code | Quando | | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | A série, a temporada ou o episódio não existe, por exemplo a temporada `0` em uma série sem especiais, ou o caminho não é oferecido. | | 405 | 37 | Você chamou um método de escrita. | | 429 | 25 | Você passou do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | Veja [erros](https://amodb.dev/pt/errors/) para o formato completo do corpo e [limites de requisições](https://amodb.dev/pt/rate-limits/) para as janelas. ## Notas práticas - Temporadas e episódios têm cache de 6 horas. Releia a temporada atual uma ou duas vezes por dia enquanto a série está no ar. - Uma série de 10 temporadas precisa de 10 chamadas de temporada. No plano de 20 requisições por minuto isso usa metade da cota de um minuto, e uma nova execução dentro de 6 horas é atendida pelo cache de borda. - Um episódio ainda não exibido pode ter `air_date` null, `runtime` null e `overview` vazio. Renderize um espaço reservado em vez de falhar. - Stills são quadros largos, não pôsteres. Peça `w300` nas listas e `original` só quando precisar da visualização em tamanho total. ## Perguntas e respostas ### Como listo todos os episódios de uma série? Leia number_of_seasons no registro da série e depois chame o endpoint de temporada uma vez por número de temporada. Cada resposta de temporada traz o array episodes completo, então uma série de cinco temporadas leva cinco requisições. ### O que significa o número de temporada 0? A temporada 0 guarda especiais, como bastidores e resumos. Ela só existe quando a série tem especiais, e uma série sem eles retorna 404 com status_code 34 para a temporada 0. ### Por que air_date é null em alguns episódios? O episódio foi anunciado, mas ainda não tem data confirmada. Trate null como sem agenda e confira next_episode_to_air no registro da série para achar o próximo episódio com data. ### Posso obter a ordem de DVD ou a ordem absoluta dos episódios? Não como uma listagem separada. GET /3/tv/{series_id}/episode_groups nomeia as ordens que uma série tem, mas o amodb não oferece um endpoint que retorne os episódios de um grupo. O endpoint de temporada dá a ordem padrão. ## Páginas relacionadas - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [API de créditos](https://amodb.dev/pt/credits/): API de créditos com caminhos e JSON iguais aos do TMDB v3. Elenco e equipe técnica de filmes, séries, temporadas e episódios, com order, department e job. - [API de imagens e host de imagens](https://amodb.dev/pt/images-api/): API de imagens de filmes com caminhos do TMDB v3: liste pôsteres, backdrops, logos e stills por título e carregue-os de img.amodb.dev em 10 tamanhos, sem chave. - [API de guia de episódios](https://amodb.dev/pt/episode-guide-api/): API de guia de episódios com os endpoints de temporada e episódio do TMDB v3: nomes, datas de exibição, durações, imagens e grupos de episódios, em 14 idiomas. - [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After. - [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/tv-seasons-episodes/