API даведніка па эпізодах

API даведніка па эпізодах пералічвае кожны эпізод серыяла праз GET /3/tv/{tv_id}/season/{season_number}. Кожны эпізод мае назву, апісанне, дату эфіру, працягласць і кадр. Спіс episode_groups называе альтэрнатыўныя парадкі, напрыклад DVD або абсалютны. Шляхі і JSON адпавядаюць TMDB v3, таму існуючым кліентам трэба толькі новы базавы URL.

Глядзець тарыфы Адкрыць хуткі старт

Запыт

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

Адказ 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,

Атрыманне ўсіх эпізодаў сезона

GET /3/tv/{tv_id}/season/{season_number} вяртае сезон з поўным масівам episodes. Кожны эпізод мае episode_number, name, overview, air_date, runtime і still_path. Id гэта лікавыя id, якія выкарыстоўвае TMDB, напрыклад 1396 для Breaking Bad.

Вы атрымліваеце сезоны, эпізоды з датамі і працягласцю, кадры, наступны і апошні эпізоды серыяла, што выйшлі ў эфір, і спіс альтэрнатыўных парадкаў эпізодаў. Тэкставыя палі залежаць ад параметра language, а апісанне застаецца пустым, калі перакладу няма.

Якія даныя вы атрымліваеце

Эндпоінт	Што вяртае
`GET /3/tv/{tv_id}`	Кароткае апісанне `seasons`, `number_of_seasons`, `status`, `next_episode_to_air`, `last_episode_to_air`
`GET /3/tv/{tv_id}/season/{season_number}`	Адзін сезон з усімі `episodes`
`GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}`	Адзін эпізод з `crew` і `guest_stars`
`GET /3/tv/{tv_id}/episode_groups`	Назва, `type` і колькасць эпізодаў кожнага альтэрнатыўнага парадку, вызначанага для серыяла

Палі эпізода:

Поле	Тып	Заўвагі
`id`, `show_id`	цэлы лік	Id эпізода і id серыяла. `show_id` ёсць у спісах сезона і ў `next_episode_to_air`, але не на шляху аднаго эпізода
`episode_number`, `season_number`	цэлы лік	Месца ў сезоне
`episode_type`	радок	Напрыклад `standard`
`name`, `overview`	радок	Лакалізуюцца праз `language`
`air_date`	радок або null	`YYYY-MM-DD`, пусты або null, калі не анансавана
`runtime`	цэлы лік або null	Хвіліны
`still_path`	радок або null	Далучаецца да `https://img.amodb.dev/t/p/{size}`
`vote_average`, `vote_count`	лік, цэлы лік	Цяпер `0` у эпізодаў
`production_code`	радок	Код студыі, часта пусты
`crew`, `guest_stars`	масіў	Людзі, названыя ў эпізодзе, з тымі ж палямі, што ў акцёра

Пачніце за 3 крокі

Абярыце план на старонцы цэны. Усе планы вяртаюць аднолькавыя даныя пра эпізоды, адрозніваецца толькі частата запытаў.
Стварыце ключ у асабістым кабінеце і захавайце яго ў зменнай асяроддзя.
Запытайце /3/tv/{tv_id}/season/1 з ключом у загалоўку Bearer або як api_key.

Прыклад запыту

У прыкладзе па-англійску загружаецца сезон 1 Breaking Bad (id серыяла 1396). Праграма на Go дэкадуе яго ў тыпізаваныя структуры і друкуе па радку на эпізод з датай эфіру, працягласцю і URL кадра.

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

Скарочаны адказ: 2 з 7 эпізодаў, у кожнага па адным члене групы і адной запрошанай зорцы.

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
}

Загрузка ўсяго серыяла

amodb не прымае значэнні ў стылі season/1 у append_to_response, таму выклікі сезонаў застаюцца асобнымі. Спачатку прачытайце number_of_seasons і спіс seasons з дэталяў серыяла, потым запытвайце кожны сезон у цыкле.

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 уключае сезон 0, калі ў серыяла ёсць спецвыпускі, таму Breaking Bad каштуе 1 выклік дэталяў плюс 6 выклікаў сезонаў. Серыял з 10 сезонамі каштуе 11 запытаў. Дэталі кэшуюцца на edge на 6 гадзін, таму захавайце вынік і абнаўляйце яго па раскладзе.

Даты эфіру і што далей

GET /3/tv/{tv_id} змяшчае next_episode_to_air і last_episode_to_air, поўныя аб’екты эпізодаў з name, air_date, season_number, episode_number, runtime і still_path. next_episode_to_air роўны null, калі нічога не анансавана. Спалучайце яго са status (напрыклад Returning Series, Ended або Canceled), каб вырашыць, ці паказваць зваротны адлік.

air_date гэта каляндарная дата без часу сутак. Параўноўвайце яе з сённяшняй датай, каб пазначаць новыя эпізоды. Для раскладу таго, што ідзе ў эфіры, спісы airing_today і on_the_air на старонцы трэнды і спісы кэшуюцца на 30 хвілін.

Кадры і працягласць

Выкарыстоўвайце w185 або w300 для радкоў спісу і original для поўнага памеру. Памеры кадраў: w92, w185, w300 і original. У эпізода можа не быць кадра, таму паказвайце запаўняльнік, калі still_path роўны null. Хост выяў не патрабуе ключа, гл. выявы.

runtime вымяраецца ў хвілінах і можа быць null. Каб паказаць час марафона для сезона, складзіце runtime усіх episodes і лічыце null за 0. Дадайце append_to_response=credits,images на шляху аднаго эпізода, каб атрымаць аб’ект credits і спіс stills. Масіў cast эпізода пусты, а людзі знаходзяцца ў crew і guest_stars. Падрабязнасці на старонках сезоны і эпізоды і удзельнікі.

Альтэрнатыўныя парадкі з групамі эпізодаў

Некаторыя серыялы глядзяць у іншым парадку, чым яны выходзілі. GET /3/tv/{tv_id}/episode_groups пералічвае парадкі, вызначаныя для серыяла. Кожны запіс мае id, name, description, type, episode_count, group_count і network. Масіў results пусты, калі нічога не вызначана.

`type`	Парадак
1	Арыгінальная дата эфіру
2	Абсалютны
3	DVD
4	Лічбавы
5	Па сюжэтных лініях
6	Вытворчы
7	ТБ

amodb вяртае толькі гэты спіс. Ён не прапануе GET /3/tv/episode_group/{id}, таму эпізоды ўнутры групы недаступныя. Для даных пра эпізоды выкарыстоўвайце эндпоінты сезонаў.

Параўнанне

Магчымасць	Скрэйпінг старонак эпізодаў	API метаданых з бясплатным тарыфам	amodb
Увесь сезон	Адзін запыт старонкі на сезон	Глядзіце іх дакументацыю	Адзін выклік, масіў `episodes` уключаны
Увесь серыял	Абыйсці кожны сезон	Глядзіце іх дакументацыю	Адзін выклік на сезон, пералічаныя ў `seasons`
Даты эфіру	Разбіраць тэкст	Глядзіце іх дакументацыю	`air_date` плюс `next_episode_to_air`
Кадры	Спампоўваць і змяняць памер	Глядзіце іх дакументацыю	Фіксаваныя памеры на `img.amodb.dev`, без ключа
Іншыя парадкі эпізодаў	Недаступна	Глядзіце іх дакументацыю	Спіс `episode_groups`, змест груп не аддаецца
Мовы	Адна лакаль на сайт	Глядзіце іх дакументацыю	14 моў праз `language`

Цэны

Планы аплачваюцца наперад на 1, 3, 6, 12 або 24 месяцы са зніжкай 0, 10, 20, 30 або 40 працэнтаў на доўгія перыяды і ніколі не прадаўжаюцца самі. Планы на 20, 40 і 120 запытаў у хвіліну вяртаюць кожны эндпоінт на гэтай старонцы. Абнаўленне серыяла каштуе адзін запыт на дэталі і па адным на сезон. Бясплатнага тарыфа няма. Абярыце план на старонцы цэны.

Пытанні і адказы

Як атрымаць спіс усіх эпізодаў серыяла?

Прачытайце number_of_seasons з GET /3/tv/{tv_id}, потым выклічце GET /3/tv/{tv_id}/season/{season_number} для кожнага сезона. Кожны адказ па сезоне змяшчае поўны масіў episodes, таму асобны выклік на эпізод не патрэбны. Некалькі сезонаў вяртаюцца з пустым масівам episodes, калі даных пра эпізоды няма.

Ці можна атрымаць некалькі сезонаў адным запытам?

Не. amodb ігнаруе значэнні ў стылі season/1 у append_to_response, таму кожны сезон ёсць асобным запытам. Серыял з 10 сезонамі каштуе 11 запытаў: адзін на дэталі і па адным на сезон.

Што такое група эпізодаў?

Група эпізодаў гэта альтэрнатыўны парадак тых жа эпізодаў, напрыклад парадак DVD, абсалютны або па сюжэтных лініях. GET /3/tv/{tv_id}/episode_groups пералічвае іх з name, type і колькасцю эпізодаў. amodb не аддае эпізоды ўнутры групы.

Як даведацца, калі выйдзе наступны эпізод?

GET /3/tv/{tv_id} вяртае next_episode_to_air з air_date, season_number і episode_number. Значэнне роўнае null, калі нічога не анансавана. last_episode_to_air дае самы апошні эпізод.

Адкуль бяруцца выявы эпізодаў?

Кожны эпізод мае still_path. Далучыце яго да https://img.amodb.dev/t/p/{size}, напрыклад w300 для радкоў спіса. Выявы не патрабуюць ключа. still_path можа быць null, таму трымайце напагатове запаўняльнік.

Абноўлена 18 кас 2026 г.

Адкрыць у Markdown

Пачніце з аднаго ключа

Кожны тарыф дае доступ да тых самых даных, усіх 14 моў і выяў. Тарыфы адрозніваюцца колькасцю запытаў у хвіліну, а Pro+ атрымлівае яшчэ і /3/all: усё пра фільм, серыял або персону ў адным запыце.

ад 3,11 $ у месяц