# API de guia de episódios > A API de guia de episódios lista todos os episódios de uma série por meio de GET /3/tv/{tv_id}/season/{season_number}. Cada episódio tem nome, sinopse, data de exibição, duração e imagem de cena. A lista episode_groups nomeia ordens alternativas, como DVD ou absoluta. Caminhos e JSON seguem o TMDB v3, então clientes existentes só precisam de uma nova URL base. ## Obtenha todos os episódios de uma temporada `GET /3/tv/{tv_id}/season/{season_number}` retorna uma temporada com o array `episodes` completo. Cada episódio tem `episode_number`, `name`, `overview`, `air_date`, `runtime` e `still_path`. Os IDs são os IDs numéricos que o TMDB usa, por exemplo `1396` para Breaking Bad. Você recebe temporadas, episódios com datas e durações, imagens de cena, o próximo e o último episódio exibido de uma série e a lista de ordens alternativas de episódios. Os campos de texto seguem o parâmetro `language`, e a sinopse fica vazia quando não existe tradução. ## Quais dados você recebe | Endpoint | Retorna | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `GET /3/tv/{tv_id}` | Resumo de `seasons`, `number_of_seasons`, `status`, `next_episode_to_air`, `last_episode_to_air` | | `GET /3/tv/{tv_id}/season/{season_number}` | Uma temporada com todos os seus `episodes` | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}` | Um episódio com `crew` e `guest_stars` | | `GET /3/tv/{tv_id}/episode_groups` | Nome, `type` e contagem de episódios de cada ordem alternativa definida para a série | Campos de um episódio: | Campo | Tipo | Observações | | --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id`, `show_id` | inteiro | ID do episódio e ID da série. `show_id` aparece nas listas de temporada e em `next_episode_to_air`, não no caminho de um único episódio | | `episode_number`, `season_number` | inteiro | Posição na temporada | | `episode_type` | string | Por exemplo `standard` | | `name`, `overview` | string | Localizados com `language` | | `air_date` | string ou null | `YYYY-MM-DD`, vazio ou null quando não anunciado | | `runtime` | inteiro ou null | Minutos | | `still_path` | string ou null | Junte a `https://img.amodb.dev/t/p/{size}` | | `vote_average`, `vote_count` | número, inteiro | Atualmente `0` nos episódios | | `production_code` | string | Código do estúdio, muitas vezes vazio | | `crew`, `guest_stars` | array | Pessoas creditadas no episódio, com os mesmos campos de um membro do elenco | ## Comece em 3 passos 1. Escolha um plano em [preços](https://amodb.dev/pt/pricing/). Todos os planos retornam os mesmos dados de episódios, e só o limite de requisições muda. 2. Crie uma chave no painel da sua conta e guarde-a em uma variável de ambiente. 3. Faça a requisição de `/3/tv/{tv_id}/season/1` com a chave como cabeçalho Bearer ou como `api_key`. ## Exemplo de requisição O exemplo busca a temporada 1 de Breaking Bad (ID da série `1396`) em inglês. O programa em Go a decodifica em structs tipadas e imprime uma linha por episódio com a data de exibição, a duração e a URL da imagem de cena. ```bash curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Episode struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` StillPath *string `json:"still_path"` } type Season struct { Name string `json:"name"` SeasonNumber int `json:"season_number"` Episodes []Episode `json:"episodes"` } func main() { client := &http.Client{Timeout: 10 * time.Second} url := "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" req, err := http.NewRequest("GET", url, nil) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(fmt.Sprintf("amodb returned %s", res.Status)) } var season Season if err := json.NewDecoder(res.Body).Decode(&season); err != nil { panic(err) } fmt.Println(season.Name) for _, e := range season.Episodes { still := "no still" if e.StillPath != nil { still = "https://img.amodb.dev/t/p/w300" + *e.StillPath } fmt.Printf("S%02dE%02d %s %3d min %s %s\n", season.SeasonNumber, e.EpisodeNumber, e.AirDate, e.Runtime, e.Name, still) } } ``` Resposta reduzida: 2 dos 7 episódios, com um membro da equipe técnica e um convidado especial cada. ```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...", "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" } ], "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" } ] }, { "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 mor...", "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" } ], "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" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Busque uma série inteira O amodb não aceita valores no estilo `season/1` em `append_to_response`, então as chamadas de temporada ficam separadas. Leia primeiro `number_of_seasons` e a lista `seasons` dos detalhes da série, depois peça cada temporada em um loop. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path) { const res = await fetch(base + path, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const show = await get('/tv/1396'); for (const { season_number } of show.seasons) { const season = await get(`/tv/1396/season/${season_number}`); console.log(season.name, season.episodes.length); } ``` `seasons` inclui a temporada 0 quando a série tem especiais, então Breaking Bad custa 1 chamada de detalhes mais 6 chamadas de temporada. Uma série com 10 temporadas custa 11 requisições. Os detalhes ficam em cache de borda por 6 horas, então guarde o resultado e atualize-o em um agendamento. ## Datas de exibição e o que vem a seguir `GET /3/tv/{tv_id}` traz `next_episode_to_air` e `last_episode_to_air`, objetos de episódio completos com `name`, `air_date`, `season_number`, `episode_number`, `runtime` e `still_path`. `next_episode_to_air` é `null` quando nada foi anunciado. Combine-o com `status` (por exemplo `Returning Series`, `Ended` ou `Canceled`) para decidir se mostra uma contagem regressiva. `air_date` é uma data de calendário sem hora do dia. Compare-a com a data de hoje para marcar episódios novos. Para uma grade do que está no ar, as listas `airing_today` e `on_the_air` em [em alta e listas](https://amodb.dev/pt/trending-lists/) ficam em cache por 30 minutos. ## Imagens de cena e durações Use `w185` ou `w300` para linhas de lista e `original` para o tamanho completo. Os tamanhos de imagem de cena são `w92`, `w185`, `w300` e `original`. Um episódio pode não ter imagem de cena, então exiba um placeholder quando `still_path` for `null`. O host de imagens não exige chave, veja [imagens](https://amodb.dev/pt/images-api/). `runtime` é dado em minutos e pode ser `null`. Para mostrar o tempo de maratona de uma temporada, some `runtime` sobre `episodes` e conte `null` como 0. Adicione `append_to_response=credits,images` ao caminho de um único episódio para obter um objeto `credits` e uma lista `stills`. O array `cast` do episódio fica vazio, e as pessoas estão em `crew` e `guest_stars`. Os detalhes estão em [temporadas e episódios](https://amodb.dev/pt/tv-seasons-episodes/) e [créditos](https://amodb.dev/pt/credits/). ## Ordens alternativas com grupos de episódios Algumas séries são assistidas em uma ordem diferente da que foram ao ar. `GET /3/tv/{tv_id}/episode_groups` lista as ordens definidas para uma série. Cada entrada tem `id`, `name`, `description`, `type`, `episode_count`, `group_count` e `network`. O array `results` fica vazio quando nenhuma está definida. | `type` | Ordem | | ------ | ------------------------- | | 1 | Data original de exibição | | 2 | Absoluta | | 3 | DVD | | 4 | Digital | | 5 | Arco de história | | 6 | Produção | | 7 | TV | O amodb retorna apenas essa lista. Ele não oferece `GET /3/tv/episode_group/{id}`, então os episódios dentro de um grupo não estão disponíveis. Use os endpoints de temporada para os dados dos episódios. ## Como se compara | Recurso | Scraping de páginas de episódios | API de metadados com plano gratuito | amodb | | -------------------------- | --------------------------------- | ----------------------------------- | ------------------------------------------------------- | | Temporada completa | Uma busca de página por temporada | Consulte a documentação deles | Uma chamada, com o array `episodes` incluído | | Série inteira | Rastrear cada temporada | Consulte a documentação deles | Uma chamada por temporada, listadas em `seasons` | | Datas de exibição | Analisar texto | Consulte a documentação deles | `air_date` mais `next_episode_to_air` | | Imagens de cena | Baixar e redimensionar | Consulte a documentação deles | Tamanhos fixos em `img.amodb.dev`, sem chave | | Outras ordens de episódios | Indisponível | Consulte a documentação deles | Lista `episode_groups`, conteúdo dos grupos não servido | | Idiomas | Um idioma por site | Consulte a documentação deles | 14 idiomas via `language` | ## Preços Os planos são pré-pagos por 1, 3, 6, 12 ou 24 meses, com 0, 10, 20, 30 ou 40 por cento de desconto nos períodos mais longos, e nunca renovam sozinhos. Os planos de 20, 40 e 120 requisições por minuto retornam todos os endpoints desta página. Atualizar uma série custa uma requisição para os detalhes e uma por temporada. Não há plano gratuito. Escolha um plano em [preços](https://amodb.dev/pt/pricing/). ## Perguntas e respostas ### Como listo todos os episódios de uma série de TV? Leia number_of_seasons em GET /3/tv/{tv_id} e depois chame GET /3/tv/{tv_id}/season/{season_number} para cada temporada. Toda resposta de temporada contém o array episodes completo, então você não precisa de uma chamada separada por episódio. Algumas temporadas voltam com o array episodes vazio quando não há dados de episódios. ### Posso obter várias temporadas em uma só requisição? Não. O amodb ignora valores no estilo season/1 em append_to_response, então cada temporada é uma requisição própria. Uma série com 10 temporadas custa 11 requisições, uma para os detalhes e uma por temporada. ### O que é um grupo de episódios? Um grupo de episódios é uma ordem alternativa dos mesmos episódios, como a ordem de DVD, absoluta ou por arco de história. GET /3/tv/{tv_id}/episode_groups lista os grupos com nome, tipo e contagem de episódios. O amodb não serve os episódios dentro de um grupo. ### Como descubro quando o próximo episódio vai ao ar? GET /3/tv/{tv_id} retorna next_episode_to_air com air_date, season_number e episode_number. O valor é null quando nada foi anunciado. last_episode_to_air dá o mais recente. ### De onde vêm as imagens dos episódios? Cada episódio tem um still_path. Junte-o a https://img.amodb.dev/t/p/{size}, por exemplo w300 para linhas de lista. As imagens não exigem chave. Um still_path pode ser null, então deixe um placeholder pronto. ## Páginas relacionadas - [API de temporadas e episódios de séries](https://amodb.dev/pt/tv-seasons-episodes/): API de temporadas e episódios com os mesmos caminhos e JSON do TMDB v3. Leia uma temporada com todos os episódios, ou um episódio com data, duração e still. - [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 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 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 séries de TV: séries, temporadas e episódios](https://amodb.dev/pt/tv-show-api/): API de séries de TV com status, emissoras, temporadas, episódios e next_episode_to_air. JSON do TMDB v3 em 14 idiomas, a partir de 20 requisições por minuto. - [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/episode-guide-api/