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

Отвори като Markdown