# API de séries de TV > O endpoint de séries retorna uma série por id em GET /3/tv/{series_id}: nomes, sinopse, status, temporadas, emissoras, gêneros e ponteiros para o último e o próximo episódio. O JSON segue o TMDB v3, então os clientes existentes só precisam de uma nova URL base. Use append_to_response para juntar content ratings, credits e ratings em uma só requisição. ## Endpoint `GET /3/tv/{series_id}` ```bash curl "https://api.amodb.dev/3/tv/1396?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "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, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" }, { "id": 33742, "logo_path": "/2jdh2sEa0R6y6uT0F7g0IgA2WO8.png", "name": "High Bridge Productions", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "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 diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 }, { "air_date": "2009-03-08", "episode_count": 13, "id": 3573, "name": "第 2 季", "overview": "贩卖冰毒的沃尔特老师在毒品交易中越陷越深，这引起了竞争对手的注意并使他在缉毒局的小舅子陷入危险中。", "poster_path": "/zMO024gJxKhTJfWqM0XTYd3SgKj.jpg", "season_number": 2, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 8.955, "vote_count": 18873 } ``` ## Obter os detalhes de uma série de TV `GET /3/tv/{series_id}` retorna o registro principal de uma série: nomes, sinopse, status, gêneros, emissoras, a lista de temporadas e ponteiros para o último e o próximo episódio. O id é o id numérico de TV do TMDB, então uma série que você guarda como `1396` mantém esse id aqui. Ids de filmes e ids de séries são espaços separados, então guarde sempre o tipo de mídia junto do número. O exemplo pede Breaking Bad em inglês e acrescenta as classificações indicativas e as notas externas na mesma chamada. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' }); const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const show = await res.json(); const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US'); console.log(show.name, show.status, show.number_of_seasons, us?.rating); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396", params={"language": "en-US", "append_to_response": "content_ratings,ratings"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() show = r.json() us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None) print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"]) ``` ```php 'en-US', 'append_to_response' => 'content_ratings,ratings', ]); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $show = json_decode($body, true); echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type Show struct { Name string `json:"name"` Status string `json:"status"` NumberOfSeasons int `json:"number_of_seasons"` NumberOfEpisodes int `json:"number_of_episodes"` Next *struct { AirDate string `json:"air_date"` } `json:"next_episode_to_air"` } func main() { q := url.Values{"language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var s Show if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } next := "none scheduled" if s.Next != nil { next = s.Next.AirDate } fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next) } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | -------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------- | | `series_id` | caminho | sim | Id numérico da série, por exemplo `1396`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | | `language` | consulta | não | Tag do TMDB como `en-US`, `uk-UA` ou `es-ES`. 14 idiomas base são atendidos. Padrão `en-US`. | | `append_to_response` | consulta | não | Lista separada por vírgulas de subrecursos para juntar à resposta, até 20 valores. | ### Campos da resposta | Campo | Tipo | Observações | | -------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | inteiro | Id da série. | | `name`, `original_name` | string | Título localizado e título original. Nomes originais em japonês ou coreano ficam em `original_name`. | | `overview`, `tagline` | string | Texto localizado, vazio quando não existe tradução. | | `first_air_date`, `last_air_date` | string ou null | `YYYY-MM-DD`. | | `status` | string | Ciclo de vida, veja a tabela abaixo. | | `in_production` | booleano | `true` enquanto a série ainda está sendo produzida. | | `number_of_seasons`, `number_of_episodes` | inteiro | Totais, como guardados para a série. | | `episode_run_time` | array | Durações típicas dos episódios em minutos, pode estar vazio. | | `seasons` | array | Um resumo por temporada com `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`. | | `last_episode_to_air`, `next_episode_to_air` | objeto ou null | Resumos de episódio, no formato dos objetos de [temporadas e episódios](https://amodb.dev/pt/tv-seasons-episodes/). | | `networks`, `production_companies` | array | `id`, `name`, `logo_path`, `origin_country`. | | `production_countries`, `spoken_languages` | array | Países com `iso_3166_1` e `name`. Idiomas com `english_name`, `iso_639_1` e `name`. | | `created_by` | array | Criadores com `id`, `name`, `profile_path` e `credit_id`. Vazio para a maioria das séries. | | `genres` | array | Objetos com `id` e `name`. Os ids de gênero de séries diferem dos de filmes. | | `origin_country`, `original_language`, `languages` | array, string | Códigos de país e de idioma. | | `homepage` | string | Site oficial, vazio quando desconhecido. | | `poster_path`, `backdrop_path` | string ou null | Acrescente a `https://img.amodb.dev/t/p/{size}`. Veja [imagens](https://amodb.dev/pt/images-api/). | | `popularity` | número | Valor relativo usado pela lista de populares. | | `vote_average`, `vote_count` | número, inteiro | Nota agregada dos usuários. | | `adult` | booleano | Sempre `false`. Títulos adultos nunca são atendidos. | ### Exemplo de resposta `GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings`, com arrays e textos longos abreviados: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "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, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "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 diagnosis. Stre...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 9, "vote_count": 18863, "content_ratings": { "results": [ { "descriptors": [], "iso_3166_1": "AT", "rating": "16" }, { "descriptors": [], "iso_3166_1": "AU", "rating": "MA 15+" } ] }, "ratings": { "imdb": { "value": 9.5, "votes": 2671962 }, "kinopoisk": { "value": 8.9, "votes": null }, "metacritic": null, "rotten_tomatoes": { "value": 96, "votes": null }, "tmdb": { "value": 9, "votes": 18863 } } } ``` Os blocos `content_ratings` e `ratings` vêm de `append_to_response`. Nomes e sinopses dentro de `seasons`, `last_episode_to_air` e `next_episode_to_air` são guardados por registro e podem não seguir `language`, como mostra o nome de episódio em hebraico acima. Leia o texto localizado de temporadas e episódios no [endpoint de temporada](https://amodb.dev/pt/tv-seasons-episodes/). ## Status e ponteiros de episódio `status` diz em que ponto da vida a série está, e `next_episode_to_air` diz quando olhar de novo. | Valor de `status` | Significado | `next_episode_to_air` | | -------------------------- | -------------------------------- | ---------------------------------------------------- | | `Returning Series` | No ar agora ou entre temporadas. | Preenchido quando há uma data conhecida, senão null. | | `Planned`, `In Production` | Ainda não é uma série regular. | Em geral null. | | `Ended` | Terminou a exibição. | Null. | | `Canceled` | Parou antes do fim planejado. | Null. | Uma série em andamento entre temporadas tem `next_episode_to_air` null, então leia null como “sem data conhecida” e não como “encerrada”. O array `seasons` lista um resumo por temporada, e a temporada `0` guarda os especiais. Para ler os episódios de uma temporada, chame o endpoint de [temporadas e episódios](https://amodb.dev/pt/tv-seasons-episodes/). ## Endpoints de séries relacionados Todos os caminhos compartilham a base `https://api.amodb.dev/3`, e os endpoints com texto localizado também aceitam `language`. | Método e caminho | Retorna | Parâmetros extras | | ---------------------------------------- | --------------------------------------------------------------------------- | ----------------- | | `GET /tv/{series_id}/alternative_titles` | `{id, results}` com `iso_3166_1`, `title`, `type`, muitas vezes vazio | nenhum | | `GET /tv/{series_id}/content_ratings` | Classificação indicativa por país | nenhum | | `GET /tv/{series_id}/episode_groups` | Lista de ordenações alternativas de episódios, como DVD ou arco da história | nenhum | | `GET /tv/{series_id}/recommendations` | Uma lista de 20 séries recomendadas | nenhum | | `GET /tv/{series_id}/similar` | Uma lista de 20 séries semelhantes | nenhum | | `GET /tv/{series_id}/reviews` | `results` está vazio para a maioria das séries | nenhum | | `GET /tv/{series_id}/lists` | Listas públicas que contêm a série | `page` | | `GET /tv/{series_id}/watch/providers` | Provedores de streaming, aluguel e compra por país | nenhum | | `GET /tv/latest` | O registro de série mais novo adicionado | nenhum | As listas de recomendações e de semelhantes sempre retornam a página 1 com 20 itens. A resposta de `lists` é paginada com `page`, 20 listas por página. As outras listas paginadas da API aceitam `page` de 1 a 500. As classificações indicativas voltam como entradas de `results` com `iso_3166_1`, `rating` e `descriptors`, então escolha a entrada que corresponde ao país do espectador. Os provedores de streaming são indexados por código de país, e cada país traz um `link` mais as listas `flatrate`, `rent` e `buy` com `provider_id`, `provider_name`, `logo_path` e `display_priority`. Os ids de provedores para filtrar vêm das listas de consulta em [gêneros e listas de consulta](https://amodb.dev/pt/genres/). A lista de grupos de episódios retorna `id` (uma string), `name`, `description`, `type`, `episode_count`, `group_count` e `network`. O amodb lista os grupos, mas não oferece um endpoint que retorne os episódios de um grupo. Ele também não oferece os caminhos `changes` do TMDB. ## Juntar mais dados em uma só chamada Liste subrecursos em `append_to_response` e cada um chega sob a própria chave. A chamada inteira conta uma vez nas suas 20, 40 ou 120 requisições por minuto. Funcionam até 20 valores, e nomes desconhecidos são ignorados sem erro. Estes valores funcionam em uma série: | Valor | Adiciona | Detalhes | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credits` | Elenco e equipe técnica | [Créditos](https://amodb.dev/pt/credits/) | | `external_ids` | Ids como `imdb_id`, `tvdb_id` e `wikidata_id` | [Buscar por ID externo](https://amodb.dev/pt/find-by-external-id/) | | `images`, `videos` | Pôsteres, imagens de fundo (backdrop), trailers | [Imagens](https://amodb.dev/pt/images-api/), [Vídeos](https://amodb.dev/pt/videos-trailers/) | | `keywords`, `translations` | Tags e textos traduzidos | [Palavras-chave](https://amodb.dev/pt/keywords/), [Traduções](https://amodb.dev/pt/translations/) | | `content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews` | Os subrecursos da tabela acima | Esta página | | `ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes` | Extras do amodb | [Avaliações](https://amodb.dev/pt/ratings/), [Moods](https://amodb.dev/pt/moods/), [Trilhas sonoras](https://amodb.dev/pt/soundtracks/), [Horários de sessões](https://amodb.dev/pt/showtimes/) | ## Erros Uma chamada com falha retorna o corpo de erro do TMDB. Um id errado dá `status_code` 34 com a mensagem “The resource you requested could not be found.” | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------------------------------------- | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | Nenhuma série com esse id, um título adulto ou um caminho que não é oferecido. | | 405 | 37 | Você chamou um método de escrita, como avaliar uma série. | | 429 | 25 | Você passou do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | A lista completa está em [erros](https://amodb.dev/pt/errors/), e os limites por plano estão em [limites de requisições](https://amodb.dev/pt/rate-limits/). ## Notas práticas - Os detalhes da série e todos os subrecursos acima têm cache de 6 horas. Consulte `last_episode_to_air` no máximo algumas vezes por dia. - Peça o idioma que você exibe. Um `overview` vazio significa que não existe tradução, então peça de novo com `en-US` para ter um fallback. - Use `number_of_seasons` como limite do laço quando buscar todas as temporadas, uma chamada para cada. - Para listar séries em vez de ler uma só, veja [busca](https://amodb.dev/pt/search/), [discover](https://amodb.dev/pt/discover/) e [em alta e listas](https://amodb.dev/pt/trending-lists/). ## Perguntas e respostas ### Como sei se uma série ainda está no ar? Leia status junto com next_episode_to_air. Uma série em andamento com next_episode_to_air diferente de null tem um episódio agendado. Séries encerradas e canceladas sempre retornam null aí, e uma série entre temporadas também pode retornar. ### O registro da série inclui um id do IMDb? Não no registro base, como no TMDB. Use append_to_response=external_ids para receber imdb_id e tvdb_id, ou chame o endpoint find com um id do IMDb para ir de um id externo ao id da série. ### Posso obter as notas do IMDb e do Rotten Tomatoes de uma série? Sim. Chame GET /3/tv/{series_id}/ratings ou use append_to_response=ratings. Você recebe as notas do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB, cada uma como value e votes, ou null quando a nota não é conhecida. ### Por quanto tempo os dados de séries ficam em cache? Os detalhes da série e seus subrecursos ficam em cache de borda por 6 horas, então um episódio recém-exibido pode aparecer em last_episode_to_air com esse atraso. Listas como a de séries no ar têm cache de 30 minutos. ## Páginas relacionadas - [API de temporadas e episódios de séries](https://amodb.dev/pt/tv-seasons-episodes/): API de temporadas e episódios com os mesmos caminhos e JSON do TMDB v3. Leia uma temporada com todos os episódios, ou um episódio com data, duração e still. - [API de créditos](https://amodb.dev/pt/credits/): API de créditos com caminhos e JSON iguais aos do TMDB v3. Elenco e equipe técnica de filmes, séries, temporadas e episódios, com order, department e job. - [Avaliações de filmes e séries](https://amodb.dev/pt/ratings/): API de avaliações de filmes com as notas do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB em uma só chamada, com null se a fonte for desconhecida. - [API de séries de TV: séries, temporadas e episódios](https://amodb.dev/pt/tv-show-api/): API de séries de TV com status, emissoras, temporadas, episódios e next_episode_to_air. JSON do TMDB v3 em 14 idiomas, a partir de 20 requisições por minuto. - [Erros](https://amodb.dev/pt/errors/): Todos os erros do amodb com status HTTP, status_code e mensagem do TMDB, mais o formato de erro do OMDb. O que cada um significa e o que seu cliente deve fazer. - [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/tv-series/