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.

Ver planos Ler o guia rápido

Requisição

curl Go

bashgo

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

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 200

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

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

Escolha um plano em preços. Todos os planos retornam os mesmos dados de episódios, e só o limite de requisições muda.
Crie uma chave no painel da sua conta e guarde-a em uma variável de ambiente.
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.

curl Go

bashgo

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

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.

JavaScript

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

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 e créditos.

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.

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.

Atualizado em 18 de out. de 2026

Ver em Markdown