# API seriale TV pentru seriale, sezoane și episoade

> API-ul pentru seriale TV întoarce un serial la GET /3/tv/{series_id} cu starea, rețelele, lista de sezoane și next_episode_to_air. Endpoint-urile de sezon și de episod adaugă date de difuzare, durate și cadre. JSON-ul se potrivește cu TMDB v3, în 14 limbi, pe planuri plătite în avans de 20, 40 sau 120 de cereri pe minut.

## Un API de seriale TV cu stare, sezoane și următorul episod

`GET /3/tv/{series_id}` întoarce un serial cu `status`, `networks`, lista `seasons`, `last_episode_to_air` și `next_episode_to_air`. Endpoint-urile de sezon și de episod adaugă date de difuzare, durate și cadre. amodb este un API independent care vorbește protocolul TMDB v3, deci un client scris pentru TMDB funcționează după ce schimbi URL-ul de bază în `https://api.amodb.dev/3`.

Ce primești:

- Înregistrări de seriale cu numărul de sezoane și de episoade, plus prima și ultima dată de difuzare.
- Un șir `status` și un indicator `in_production`.
- Rețele cu ID-uri, logo-uri și țara de origine.
- Un apel pe sezon, care întoarce toate episoadele sezonului.
- Liste de seriale care se difuzează azi sau în următoarele 7 zile.

## Ce date primești

| Ai nevoie de                | Apel                                                                    | Câmpuri cheie                                                                                 |
| --------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Fișa serialului             | `GET /3/tv/{series_id}`                                                 | `name`, `original_name`, `status`, `in_production`, `number_of_seasons`, `number_of_episodes` |
| Următorul și ultimul episod | același apel                                                            | `next_episode_to_air`, `last_episode_to_air`                                                  |
| Un sezon                    | `GET /3/tv/{series_id}/season/{season_number}`                          | `episodes`, `air_date`, `poster_path`                                                         |
| Un episod                   | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`, `overview`, `runtime`, `still_path`, `air_date`                                       |
| O rețea                     | `GET /3/network/{network_id}`                                           | `name`, `headquarters`, `origin_country`                                                      |

Listele complete de câmpuri sunt la [seriale TV](https://amodb.dev/ro/tv-series/) și [sezoane și episoade](https://amodb.dev/ro/tv-seasons-episodes/).

## Începe în 3 pași

1. Deschide [prețuri](https://amodb.dev/ro/pricing/) și alege planul cu ritmul de cereri de care ai nevoie: 20, 40 sau 120 pe minut.
2. Creează o cheie API în panoul contului tău.
3. Trimite `GET /3/tv/{series_id}` cu `Authorization: Bearer YOUR_API_KEY` sau adaugă `api_key` ca parametru de interogare.

## Exemplu de cerere

Scriptul citește Breaking Bad (ID de serial 1396), afișează starea și următorul episod, apoi listează sezonul 1. Salvează-l ca `check.mjs` și rulează-l cu Node 18 sau mai nou.

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

Un răspuns de serial scurtat pentru `language=en-US`. Sunt păstrate doar unele câmpuri, iar `seasons` arată primele 2 din cele 6 intrări. Unele nume nu urmează `language` în aceste date: numele sezonului 0 este în chineză, iar `name` din `last_episode_to_air` este în ebraică.

```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"
}
```

## Citirea stării și a următorului episod

Șirul `status` îți spune cum să etichetezi un serial. `next_episode_to_air` este un obiect doar cât timp un episod este programat, deci este null între sezoane, ca și după final. Testează `status` înainte să afișezi „încheiat”.

| `status`         | Semnificație                        | Ce afișezi                                                     |
| ---------------- | ----------------------------------- | -------------------------------------------------------------- |
| Returning Series | Se așteaptă mai multe episoade      | Data următoarei difuzări dacă obiectul există, altfel „revine” |
| In Production    | Se produce, încă nu e în difuzare   | „În producție”                                                 |
| Planned          | Doar anunțat                        | „Planificat”                                                   |
| Pilot            | Există doar un pilot                | „Pilot”                                                        |
| Ended            | Difuzarea s-a încheiat              | „Încheiat” și `last_air_date`                                  |
| Canceled         | Oprit înainte de finalul planificat | „Anulat”                                                       |

Câmpurile din `next_episode_to_air` și `last_episode_to_air`: `air_date`, `season_number`, `episode_number`, `episode_type`, `id`, `show_id`, `name`, `overview`, `runtime` și `still_path`. Șirul `status` poate fi gol la câteva titluri, așa că ține pregătită o etichetă neutră.

Detaliile sunt ținute în cache la margine 6 ore, deci cererea aceluiași serial de mai mult de patru ori pe zi întoarce același corp. Interoghează serialele urmărite o dată sau de două ori pe zi și reîmprospătează-l pe cel pe care îl deschide un utilizator.

## Sezoane, episoade și ce se difuzează

Sezonul 0, când un serial are unul, conține episoadele speciale. Sezoanele obișnuite încep de la 1.

| Apel                                           | Întoarce                                     | Parametri                                         |
| ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------- |
| `GET /3/tv/{series_id}/season/{season_number}` | Fișa sezonului cu un array `episodes`        | `language`, `append_to_response`                  |
| `GET /3/tv/airing_today`                       | Seriale cu un episod difuzat azi             | `page`, `language`                                |
| `GET /3/tv/on_the_air`                         | Seriale difuzate în săptămâna următoare      | `page`, `language`                                |
| `GET /3/discover/tv`                           | Seriale filtrate după rețea, stare și altele | `with_networks`, `with_status`, `sort_by`, `page` |

Rezultatele listelor și ale discover sunt ținute în cache 30 de minute, deci o cerere la jumătate de oră ajunge pentru o insignă „difuzare în curând”. Potrivește ID-urile întoarse cu serialele urmărite de utilizatori. Detaliile de sezon și de episod sunt tratate pe pagina [ghid de episoade](https://amodb.dev/ro/episode-guide-api/).

## Construirea unei liste de urmărire cu numărătoare inversă

Un ecran „serialele pe care le urmăresc” cere un ID stocat pentru fiecare serial și un mic job zilnic.

1. Salvează `id` din fișa serialului când un utilizator începe să urmărească un serial.
2. O dată pe zi, apelează `/3/tv/{series_id}` pentru fiecare ID urmărit și stochează `status`, `next_episode_to_air` și `last_air_date`.
3. Când `next_episode_to_air` este un obiect, afișează `air_date` ca dată. Nu are oră și nici fus orar, așa că nu număra invers până la minut.
4. Când este null, iar `status` este Returning Series, afișează „sezon nou neprogramat”.
5. Preia apelul de sezon doar când un utilizator deschide serialul, pentru că este cel mai mare răspuns.

Un 404 cu `status_code` 34 înseamnă că ID-ul este necunoscut, iar un 429 înseamnă că ai depășit cererile pe minut: așteaptă numărul de secunde din `Retry-After`. Cu 200 de seriale urmărite, o trecere zilnică înseamnă 200 de cereri, cam zece minute la 20 de cereri pe minut. Vezi [limite de cereri](https://amodb.dev/ro/rate-limits/) și [erori](https://amodb.dev/ro/errors/).

## Cum se compară

| Capacitate                          | Extragi singur paginile              | API de metadate cu nivel gratuit       | amodb                                                 |
| ----------------------------------- | ------------------------------------ | -------------------------------------- | ----------------------------------------------------- |
| Structura sezoanelor și episoadelor | Reconstruită din machetele paginilor | Variază, verifică documentația         | Apel de sezon cu un array `episodes`                  |
| Data următoarei difuzări            | Extrasă dintr-o pagină de program    | Variază, verifică documentația         | `next_episode_to_air`, null când nu e programat nimic |
| Starea serialului                   | Text liber pe o pagină               | Variază, verifică documentația         | Șirul `status` și indicatorul `in_production`         |
| Difuzate săptămâna aceasta          | Extragi un program                   | Variază, verifică documentația         | `/3/tv/on_the_air` și `/3/tv/airing_today`            |
| Limbi                               | Ce oferă pagina                      | Variază                                | 14, alese cu `language`                               |
| Condiții de acces                   | Se aplică termenii site-ului         | Nivel gratuit cu condiții de utilizare | Cu plată, plătit în avans, fără nivel gratuit         |

## Prețuri

Plătești o singură dată pentru 1, 3, 6, 12 sau 24 de luni. Perioadele mai lungi au reduceri de 10, 20, 30 sau 40 la sută, iar nimic nu se reînnoiește automat. Fiecare plan primește toate datele despre seriale TV, cu 20, 40 sau 120 de cereri pe minut ca unică diferență. Vezi [prețuri](https://amodb.dev/ro/pricing/), creează o cheie, iar primul tău apel de serial costă o cerere.

## Întrebări și răspunsuri

### Cum aflu dacă un serial TV încă se difuzează?

Citește status la /3/tv/{id}. Returning Series înseamnă că se așteaptă mai multe episoade, iar Ended și Canceled înseamnă că nu. Câmpul next_episode_to_air conține următorul episod programat și este null când nu e programat nimic.

### Pot prelua toate episoadele unui serial într-o singură cerere?

Câte un sezon pe apel. GET /3/tv/{id}/season/{n} întoarce toate episoadele sezonului într-un array episodes, deci un serial cu cinci sezoane cere cinci apeluri de sezon plus un apel de serial.

### Ce primesc pentru o rețea?

Array-ul networks al unui serial listează id, name, logo_path și origin_country. GET /3/network/{id} adaugă detalii, iar with_networks în /3/discover/tv listează serialele unei rețele.

### Pot lista serialele care se difuzează azi?

Da. /3/tv/airing_today listează serialele cu un episod difuzat azi, iar /3/tv/on_the_air acoperă următoarele 7 zile. Ambele sunt paginate, primesc language și stau în cache-ul la margine 30 de minute.

### Există un nivel gratuit pentru API-ul de seriale TV?

Nu există nivel gratuit și nici perioadă de probă. Plătești în avans pentru 1, 3, 6, 12 sau 24 de luni și nimic nu se reînnoiește singur. Fiecare plan întoarce toate datele, iar planurile diferă doar prin cereri pe minut.

## Pagini conexe

- [API seriale TV](https://amodb.dev/ro/tv-series/): API seriale TV cu căile și JSON-ul TMDB v3. Preia un serial după ID cu sezoane, rețele și următorul episod, plus clasificări de conținut și furnizori.
- [API sezoane și episoade TV](https://amodb.dev/ro/tv-seasons-episodes/): API sezoane și episoade TV cu aceleași căi și același JSON ca TMDB v3. Citește un sezon cu toate episoadele sau un episod cu data difuzării, durata și cadrul.
- [API ghid de episoade](https://amodb.dev/ro/episode-guide-api/): API ghid de episoade pe endpoint-urile TMDB v3: nume, date de difuzare, durate, cadre și liste de grupuri de episoade pentru orice serial, în 14 limbi.
- [Companii și rețele](https://amodb.dev/ro/companies-networks/): Caută companii de producție și rețele TV cu căi TMDB v3. Citește numele, țara și logoul după ID, apoi filtrează discover după ID-ul unei companii sau rețele.
- [Endpoint-uri pentru tendințe și liste](https://amodb.dev/ro/trending-lists/): API filme în tendințe cu căi TMDB v3: topuri pe zi și săptămână, plus now playing, populare, bine cotate și viitoare pentru filme și TV, în cache 30 de minute.
- [Ghid rapid](https://amodb.dev/ro/quickstart/): Fă primul apel amodb: ia o cheie, cere detaliile unui film în curl, JavaScript, Python, PHP sau Go, apoi încarcă posterul de pe img.amodb.dev. Sub 2 minute.

Actualizat: 2026-10-18. Source: https://amodb.dev/ro/tv-show-api/