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.

Ver planos Ler o guia rápido

Requisição

curl JavaScript

bashjs

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"

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

Resposta 200

{
  "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,

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 e temporadas e episódios.

Comece em 3 passos

Abra preços e escolha o plano com a taxa de requisições de que você precisa: 20, 40 ou 120 por minuto.
Crie uma chave de API no painel da sua conta.
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.

curl JavaScript

bashjs

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"

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.

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.

Guarde o id da série quando um usuário passar a acompanhá-la.
Uma vez por dia, chame /3/tv/{series_id} para cada id acompanhado e guarde status, next_episode_to_air e last_air_date.
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.
Quando ele for null e status for Returning Series, mostre “nova temporada não agendada”.
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 e erros.

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, 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.

Atualizado em 18 de out. de 2026

Ver em Markdown