# API de coleções > Uma coleção reúne os filmes de uma mesma franquia, como uma trilogia ou uma longa série de filmes. GET /3/collection/{collection_id} retorna nome, sinopse, imagens e um array parts com os filmes em ordem de lançamento. Os filmes apontam de volta para a coleção por belongs_to_collection, então você navega nos dois sentidos. ## Endpoint `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## Obter uma coleção `GET /3/collection/{collection_id}` retorna uma franquia: nome, sinopse, um pôster, uma imagem de fundo (backdrop) e o array `parts`. Cada parte é um resumo de filme com os campos de que você precisa para um card, então uma só chamada basta para montar uma prateleira inteira da franquia. O exemplo carrega a coleção 10, os filmes de Star Wars, e imprime os filmes em ordem de lançamento. ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```php 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"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?language=en-US" req, _ := http.NewRequest("GET", url, 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 c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | --------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | caminho | sim | Id numérico da coleção, por exemplo `10`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | | `language` | consulta | não | Um dos 14 idiomas atendidos, por exemplo `en-US` ou `fr-FR`. Define o idioma do título e da sinopse de cada parte. Padrão `en-US`. | O `name` e o `overview` da própria coleção chegam como estão armazenados e não mudam com `language`. Em algumas coleções eles não estão em inglês. ### Campos da resposta | Campo | Tipo | Observações | | ---------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------- | | `id` | inteiro | Id da coleção. | | `name` | string | Nome da franquia. | | `overview` | string | Descrição curta. Vazia em algumas coleções. | | `poster_path`, `backdrop_path` | string ou null | Acrescente a `https://img.amodb.dev/t/p/{size}`. Veja [imagens](https://amodb.dev/pt/images-api/). | | `parts` | array | Resumos de filmes, com o `release_date` mais antigo primeiro. | | `parts[].id` | inteiro | Id do filme. Passe-o para os [detalhes do filme](https://amodb.dev/pt/movies/). | | `parts[].title`, `parts[].original_title` | string | Título localizado e título original. | | `parts[].overview` | string | Sinopse localizada. | | `parts[].release_date` | string | `YYYY-MM-DD`, ou uma string vazia para um filme sem data. Essas partes vêm por último. | | `parts[].media_type` | string | Sempre `movie` em uma coleção. | | `parts[].genre_ids` | array | Ids numéricos. Os nomes vêm de [gêneros](https://amodb.dev/pt/genres/). | | `parts[].adult`, `parts[].video` | booleano | `adult` é sempre `false`, porque títulos adultos não são atendidos. | | `parts[].original_language` | string | Código de idioma com duas letras. | | `parts[].popularity` | número | Valor de popularidade. | | `parts[].poster_path`, `parts[].backdrop_path` | string ou null | Imagens do filme. | | `parts[].vote_average`, `parts[].vote_count` | número, inteiro | Nota agregada dos usuários. | ### Exemplo de resposta Duas das nove partes aparecem aqui. ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` Textos longos são cortados com `...` nesta página. A resposta real traz o texto completo. ## Encontrar a coleção de um filme Raramente você começa por um id de coleção. Você começa por um filme, e o registro de [detalhes do filme](https://amodb.dev/pt/movies/) mostra a que franquia ele pertence. O campo `belongs_to_collection` é um objeto com `id`, `name`, `poster_path` e `backdrop_path`. Ele vale `null` para um filme que não faz parte de uma franquia, como o filme 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` O exemplo abaixo segue esse vínculo de um filme até a franquia em duas requisições. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## Imagens e busca O pôster e a imagem de fundo de uma franquia são os campos `poster_path` e `backdrop_path` do registro da coleção. Monte o endereço do arquivo a partir deles, como descrito em [imagens](https://amodb.dev/pt/images-api/). O amodb não oferece os caminhos `/collection/{collection_id}/images` e `/collection/{collection_id}/translations`, então uma coleção não tem lista de pôsteres alternativos nem linhas por idioma. Os títulos das partes seguem o parâmetro `language`, e [traduções](https://amodb.dev/pt/translations/) cobre os caminhos que retornam linhas por idioma. Para encontrar uma coleção pelo nome, use `GET /3/search/collection?query=matrix`, descrito em [busca](https://amodb.dev/pt/search/). Cada resultado tem `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` e `adult`. ## Erros | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------------------------------------- | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | Nenhuma coleção com esse id, ou um id que não é um número. | | 405 | 37 | Você usou um método de escrita em um caminho de coleção. | | 429 | 25 | Você passou do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | Veja [erros](https://amodb.dev/pt/errors/) para a lista completa e [limites de requisições](https://amodb.dev/pt/rate-limits/) para os limites de cada plano. ## Notas práticas - Coleções agrupam apenas filmes. Um filme tem no máximo um objeto `belongs_to_collection`, então cada filme corresponde a uma só franquia. - As partes chegam em ordem de lançamento. Filmes com data vazia vêm por último, então mostre-os como ainda sem data. - O registro da coleção fica em cache na borda por 6 horas, como os outros detalhes, então a página de uma franquia pode reutilizar uma só resposta durante esse tempo. - Uma parte traz só campos de resumo. Busque duração, créditos e avaliações de cada filme nos [detalhes do filme](https://amodb.dev/pt/movies/) quando o usuário o abrir. - Use `parts[].id` como chave de um filme, não a posição dele na franquia. Ordens e datas são corrigidas com o tempo. - Confirme que `name` está no idioma de exibição antes de mostrá-lo. Algumas coleções trazem o nome em outro idioma, e `language` não o altera. ## Perguntas e respostas ### Como saber se um filme pertence a uma coleção? Leia belongs_to_collection no registro de detalhes do filme. É um objeto com id, name, poster_path e backdrop_path, ou null quando o filme é independente. Use esse id no caminho da coleção. ### As partes voltam em ordem de lançamento? Sim. O array parts vem do mais antigo para o mais novo por release_date. Um filme sem data tem release_date vazio e fica por último, então mostre-o como ainda sem data. ### As séries de TV têm coleções? Não. Coleções agrupam filmes. Uma série é descrita por temporadas e episódios, que estão documentados nas páginas de séries de TV e de temporadas e episódios. ### Como pesquiso uma coleção pelo nome? Use o caminho de busca de coleções, por exemplo /3/search/collection?query=matrix. Ele retorna uma lista paginada com id, name e imagens. Pegue o id e chame o endpoint da coleção para ver as partes. ## Páginas relacionadas - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de busca](https://amodb.dev/pt/search/): API de busca com caminhos e JSON do TMDB v3. Encontre filmes, séries, pessoas, coleções, produtoras e palavras-chave por texto, com filtro de ano e paginação. - [API de imagens e host de imagens](https://amodb.dev/pt/images-api/): API de imagens de filmes com caminhos do TMDB v3: liste pôsteres, backdrops, logos e stills por título e carregue-os de img.amodb.dev em 10 tamanhos, sem chave. - [API de traduções](https://amodb.dev/pt/translations/): API de traduções de filmes com caminhos do TMDB v3: leia todos os títulos, sinopses e taglines de um filme, série ou episódio em todos os idiomas. - [API Discover](https://amodb.dev/pt/discover/): API Discover com os mesmos filtros do TMDB v3. Liste filmes e séries por gênero, elenco, produtora, palavra-chave, ano, nota, duração e provedor, com ordenação. - [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/collections/