# API de séries de TV: séries, temporadas e episódios > A API de séries de TV retorna uma série em GET /3/tv/{series_id} com status, emissoras, lista de temporadas e next_episode_to_air. Os endpoints de temporada e episódio acrescentam datas de exibição, durações e stills. O JSON segue o TMDB v3, em 14 idiomas, com planos pré-pagos de 20, 40 ou 120 requisições por minuto. ## Uma API de séries de TV com status, temporadas e próximo episódio `GET /3/tv/{series_id}` retorna uma série com seu `status`, `networks`, a lista `seasons`, `last_episode_to_air` e `next_episode_to_air`. Os endpoints de temporada e episódio acrescentam datas de exibição, durações e stills. O amodb é uma API independente que fala o protocolo TMDB v3, então um cliente escrito para o TMDB funciona depois que você troca a URL base para `https://api.amodb.dev/3`. O que você recebe: - Registros de séries com o número de temporadas e episódios, mais as datas da primeira e da última exibição. - Uma string `status` e uma flag `in_production`. - Emissoras com ids, logos e país de origem. - Uma chamada por temporada, que retorna todos os episódios dela. - Listas de séries que vão ao ar hoje ou nos próximos 7 dias. ## Quais dados você recebe | Você precisa de | Chamada | Campos principais | | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Registro da série | `GET /3/tv/{series_id}` | `name`, `original_name`, `status`, `in_production`, `number_of_seasons`, `number_of_episodes` | | Próximo e último episódio | mesma chamada | `next_episode_to_air`, `last_episode_to_air` | | Uma temporada | `GET /3/tv/{series_id}/season/{season_number}` | `episodes`, `air_date`, `poster_path` | | Um episódio | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`, `overview`, `runtime`, `still_path`, `air_date` | | Uma emissora | `GET /3/network/{network_id}` | `name`, `headquarters`, `origin_country` | As listas completas de campos estão em [séries de TV](https://amodb.dev/pt/tv-series/) e [temporadas e episódios](https://amodb.dev/pt/tv-seasons-episodes/). ## Comece em 3 passos 1. Abra [preços](https://amodb.dev/pt/pricing/) e escolha o plano com a taxa de requisições de que você precisa: 20, 40 ou 120 por minuto. 2. Crie uma chave de API no painel da sua conta. 3. Envie `GET /3/tv/{series_id}` com `Authorization: Bearer YOUR_API_KEY`, ou adicione `api_key` como parâmetro de consulta. ## Exemplo de requisição O script lê Breaking Bad (id de série 1396), imprime seu status e o próximo episódio e depois lista a temporada 1. Salve-o como `check.mjs` e execute com Node 18 ou mais recente. ```bash curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \ -H "Authorization: Bearer $AMODB_KEY" curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```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?language=en-US'); const next = show.next_episode_to_air; console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`); console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode is scheduled'); const season = await get('/tv/1396/season/1?language=en-US'); for (const ep of season.episodes) { console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`); } ``` Uma resposta de série reduzida para `language=en-US`. Só alguns campos foram mantidos, e `seasons` mostra as 2 primeiras de 6 entradas. Alguns nomes não seguem `language` nestes dados: o nome da temporada 0 está em chinês e o `name` dentro de `last_episode_to_air` está em hebraico. ```json { "first_air_date": "2008-01-20", "id": 1396, "in_production": false, "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "number_of_episodes": 62, "number_of_seasons": 5, "original_name": "Breaking Bad", "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagn...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "status": "Ended" } ``` ## Lendo o status e o próximo episódio A string `status` diz como rotular uma série. `next_episode_to_air` é um objeto só enquanto um episódio está agendado, então ele vale null entre temporadas e também depois do fim. Teste `status` antes de mostrar “encerrada”. | `status` | Significado | O que mostrar | | ---------------- | --------------------------------- | ------------------------------------------------------------------------ | | Returning Series | Mais episódios são esperados | A data de exibição do próximo, se o objeto existir; senão “em andamento” | | In Production | Em produção, ainda não está no ar | “Em produção” | | Planned | Apenas anunciada | “Planejada” | | Pilot | Só existe um piloto | “Piloto” | | Ended | A exibição terminou | “Encerrada” e `last_air_date` | | Canceled | Parou antes do fim planejado | “Cancelada” | Campos dentro de `next_episode_to_air` e `last_episode_to_air`: `air_date`, `season_number`, `episode_number`, `episode_type`, `id`, `show_id`, `name`, `overview`, `runtime` e `still_path`. A string `status` também pode vir vazia em alguns títulos, então tenha um rótulo neutro à mão. Os detalhes ficam em cache de borda por 6 horas, então pedir a mesma série mais de quatro vezes por dia retorna o mesmo corpo. Consulte as séries que você acompanha uma ou duas vezes por dia e atualize a que um usuário abrir. ## Temporadas, episódios e o que está no ar A temporada 0, quando a série tem uma, guarda os especiais. As temporadas regulares começam em 1. | Chamada | Retorna | Parâmetros | | ---------------------------------------------- | --------------------------------------------- | ------------------------------------------------- | | `GET /3/tv/{series_id}/season/{season_number}` | Registro da temporada com um array `episodes` | `language`, `append_to_response` | | `GET /3/tv/airing_today` | Séries com um episódio no ar hoje | `page`, `language` | | `GET /3/tv/on_the_air` | Séries no ar na próxima semana | `page`, `language` | | `GET /3/discover/tv` | Séries filtradas por emissora, status e mais | `with_networks`, `with_status`, `sort_by`, `page` | Listas e resultados do discover ficam em cache por 30 minutos, então uma requisição a cada meia hora basta para um selo de “no ar em breve”. Compare os ids retornados com as séries que seus usuários acompanham. Os detalhes de temporadas e episódios estão na página do [guia de episódios](https://amodb.dev/pt/episode-guide-api/). ## Criando uma lista de acompanhamento com contagens regressivas Uma tela de “séries que eu acompanho” precisa de um id guardado por série e de um pequeno job diário. 1. Guarde o `id` da série quando um usuário passar a acompanhá-la. 2. Uma vez por dia, chame `/3/tv/{series_id}` para cada id acompanhado e guarde `status`, `next_episode_to_air` e `last_air_date`. 3. Quando `next_episode_to_air` for um objeto, mostre `air_date` como data. Ele não traz hora do dia nem fuso horário, então não faça contagem regressiva até o minuto. 4. Quando ele for null e `status` for Returning Series, mostre “nova temporada não agendada”. 5. Chame a temporada só quando um usuário abrir a série, porque é a maior resposta. Um 404 com `status_code` 34 significa que o id é desconhecido, e um 429 significa que você passou das suas requisições por minuto: espere `Retry-After` segundos. Com 200 séries acompanhadas, uma passada diária são 200 requisições, cerca de dez minutos a 20 requisições por minuto. Veja [limites de requisições](https://amodb.dev/pt/rate-limits/) e [erros](https://amodb.dev/pt/errors/). ## Como se compara | Recurso | Fazer scraping das páginas | API de metadados com plano gratuito | amodb | | ----------------------------------- | ------------------------------------------- | ----------------------------------- | ----------------------------------------------------- | | Estrutura de temporadas e episódios | Reconstruída a partir do layout das páginas | Varia, veja a documentação | Chamada de temporada com um array `episodes` | | Próxima data de exibição | Extraída de uma página de programação | Varia, veja a documentação | `next_episode_to_air`, null quando nada está agendado | | Status da série | Texto livre em uma página | Varia, veja a documentação | String `status` e flag `in_production` | | No ar esta semana | Fazer scraping de uma programação | Varia, veja a documentação | `/3/tv/on_the_air` e `/3/tv/airing_today` | | Idiomas | O que a página oferecer | Varia | 14, escolhidos com `language` | | Termos de acesso | Valem os termos do site | Plano gratuito com termos de uso | Pago, pré-pago, sem plano gratuito | ## Preços Pague uma vez por 1, 3, 6, 12 ou 24 meses. Os períodos mais longos têm 10, 20, 30 ou 40 por cento de desconto, e nada renova automaticamente. Todo plano acessa todos os dados de TV, com 20, 40 ou 120 requisições por minuto como única diferença. Veja [preços](https://amodb.dev/pt/pricing/), crie uma chave, e sua primeira chamada de série leva uma requisição. ## Perguntas e respostas ### Como sei se uma série ainda está no ar? Leia status em /3/tv/{id}. Returning Series significa que mais episódios são esperados, enquanto Ended e Canceled significam que não há mais. O campo next_episode_to_air guarda o próximo episódio agendado e é null quando nada está agendado. ### Posso buscar todos os episódios de uma série em uma só requisição? Uma temporada por chamada. GET /3/tv/{id}/season/{n} retorna todos os episódios daquela temporada em um array episodes, então uma série de cinco temporadas leva cinco chamadas de temporada mais uma chamada da série. ### O que recebo de uma emissora? O array networks de uma série lista id, name, logo_path e origin_country. GET /3/network/{id} acrescenta detalhes, e with_networks em /3/discover/tv lista as séries de uma emissora. ### Posso listar as séries que vão ao ar hoje? Sim. /3/tv/airing_today lista séries com um episódio no ar hoje e /3/tv/on_the_air cobre os próximos 7 dias. Ambas são paginadas, aceitam language e ficam no cache de borda por 30 minutos. ### Existe plano gratuito para a API de séries de TV? Não há plano gratuito nem período de teste. Você paga adiantado por 1, 3, 6, 12 ou 24 meses e nada renova sozinho. Todo plano retorna todos os dados, e os planos diferem só nas requisições por minuto. ## 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 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 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. - [Produtoras e emissoras](https://amodb.dev/pt/companies-networks/): Consulte produtoras e emissoras de TV com caminhos do TMDB v3. Leia nome, país e logo por id e depois filtre o discover por id de produtora ou emissora. - [Endpoints de em alta e de listas](https://amodb.dev/pt/trending-lists/): API de filmes em alta com caminhos do TMDB v3: rankings do dia e da semana, listas em cartaz, populares, mais bem avaliados e em breve. Cache de 30 minutos. - [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-show-api/