# API de filmes para busca, detalhes e avaliações > O amodb é uma API de filmes paga em https://api.amodb.dev/3 com os mesmos caminhos e JSON do TMDB v3. Busque um título com /search/movie e leia o filme com append_to_response para obter elenco, trailers e avaliações em uma requisição. As respostas vêm em 14 idiomas, a partir de 20 requisições por minuto. ## Uma API de filmes que fala TMDB v3 e OMDb O amodb é uma API de filmes independente. Ela fala o mesmo protocolo do TMDB v3 e do OMDb, então um cliente escrito para qualquer um dos dois funciona depois que você troca a URL base para `https://api.amodb.dev/3` (ou `https://api.amodb.dev/omdb/` para chamadas no estilo OMDb). Você encontra um filme com `/search/movie` e depois o lê com `/movie/{movie_id}` e `append_to_response`. O que você recebe: - JSON no formato do TMDB v3, com os mesmos caminhos e parâmetros de consulta. - Títulos e sinopses em 14 idiomas, selecionados com `language`. - Elenco, equipe técnica, trailers, palavras-chave, imagens e datas de lançamento por meio de `append_to_response`. - Avaliações do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB, quando conhecidas. - Pôsteres de `https://img.amodb.dev/t/p/{size}/{file}`, sem chave. ## Quais dados você recebe | Você precisa de | Chamada | Observações | | ------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Encontrar um filme pelo título | `GET /3/search/movie?query=` | Paginado, até 20 resultados por página, cache de borda de 10 minutos. Veja [busca](https://amodb.dev/pt/search/). | | O registro principal | `GET /3/movie/{movie_id}` | Títulos, sinopse, duração, gêneros, data de lançamento. Veja [filmes](https://amodb.dev/pt/movies/). | | Elenco e equipe técnica | `append_to_response=credits` | Os campos estão descritos em [créditos](https://amodb.dev/pt/credits/). | | Trailers | `append_to_response=videos` | Retorna o array `results` com `key`, `site` e `type`. | | Notas | `append_to_response=ratings` | Cinco fontes, cada uma `{ value, votes }` ou null. Veja [avaliações](https://amodb.dev/pt/ratings/). | | Uma resposta no estilo OMDb | `GET /omdb/?t=Inception` | Mesmos campos de corpo do OMDb. Veja [endpoint OMDb](https://amodb.dev/pt/omdb-endpoint/). | ## Comece em 3 passos 1. Escolha um plano em [preços](https://amodb.dev/pt/pricing/). Os planos diferem apenas no limite: 20, 40 ou 120 requisições por minuto. 2. Crie uma chave no painel da sua conta. Uma chave tem 32 caracteres hexadecimais minúsculos. 3. Chame o endpoint com a chave no parâmetro `api_key` ou em um cabeçalho `Authorization: Bearer`. Veja [autenticação](https://amodb.dev/pt/authentication/). ## Exemplo de requisição O exemplo encontra Inception pelo título, pega o primeiro resultado e lê o filme com elenco, trailers e avaliações em mais uma chamada. São duas requisições no total. ```bash # 1. find the id curl -s "https://api.amodb.dev/3/search/movie?query=inception&language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" # 2. read the movie with extras curl -s "https://api.amodb.dev/3/movie/27205?language=en-US&append_to_response=credits,videos,ratings" \ -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, params) { const res = await fetch(`${base}${path}?${new URLSearchParams(params)}`, { headers }); if (res.status === 429) { throw new Error(`Over the limit, retry in ${res.headers.get('Retry-After')} s`); } if (!res.ok) throw new Error(`amodb returned ${res.status}`); return res.json(); } const found = await get('/search/movie', { query: 'inception', language: 'en-US' }); if (!found.results.length) throw new Error('No match'); const movie = await get(`/movie/${found.results[0].id}`, { language: 'en-US', append_to_response: 'credits,videos,ratings', }); const director = movie.credits.crew.find((c) => c.job === 'Director'); console.log(movie.title, movie.release_date, movie.runtime, director?.name); console.log('IMDb', movie.ratings.imdb?.value); ``` A resposta reduzida. Só alguns campos do registro do filme foram mantidos, `credits` foi cortado para um membro do elenco e o diretor, e o bloco `videos` foi omitido. ```json { "genres": [ { "id": 12, "name": "Adventure" }, { "id": 28, "name": "Action" }, { "id": 80, "name": "Crime" } ], "id": 27205, "imdb_id": "tt1375666", "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "runtime": 148, "title": "Inception", "credits": { "cast": [ { "adult": false, "gender": 2, "id": 6193, "known_for_department": "Acting", "name": "Leonardo DiCaprio", "original_name": "Leonardo DiCaprio", "popularity": 9.3213, "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg", "character": "Dom Cobb", "credit_id": "52fe4534c3a368484e04de03", "order": 0 } ], "crew": [ { "adult": false, "gender": 2, "id": 525, "known_for_department": "Directing", "name": "Christopher Nolan", "original_name": "Christopher Nolan", "popularity": 8.578, "profile_path": "/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg", "credit_id": "5e83ac2ee33f830018359a00", "department": "Directing", "job": "Director" } ] }, "ratings": { "imdb": { "value": 8.8, "votes": 2877173 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 74, "votes": null }, "rotten_tomatoes": { "value": 86, "votes": null }, "tmdb": { "value": 8.373, "votes": 40457 } } } ``` ## Formas de encontrar um filme Escolha a chamada que corresponde ao que você já tem. | Você começa com | Chamada | Resultado | | ---------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- | | Um título digitado por um usuário | `GET /3/search/movie?query=` | Array `results` com `id`, `title`, `release_date`, `poster_path` | | Um ID do IMDb como `tt0133093` | `GET /3/find/tt0133093?external_source=imdb_id` | Array `movie_results` | | Um ID numérico de filme como `603` | `GET /3/movie/603` | O registro completo | | Um cliente OMDb existente | `GET /omdb/?i=tt0133093` | Corpo OMDb com `Title`, `Year`, `Ratings` | Guarde os dois IDs. O `id` numérico é a chave de todas as outras chamadas, e `imdb_id` liga seus dados a outros sistemas. As regras de consulta estão em [busca por ID externo](https://amodb.dev/pt/find-by-external-id/). ## Campos vazios e consultas que falham Dados reais de filmes têm lacunas, então escreva o código de exibição pensando nelas. Uma busca sem resultado não é um erro: ela retorna HTTP 200 com um array `results` vazio. Um ID desconhecido é um erro. | Caso | O que você vê | O que fazer | | ------------------------ | -------------------------- | ----------------------------------------------- | | Busca sem resultado | 200 e `"results": []` | Mostre «sem correspondência», não tente de novo | | ID de filme desconhecido | 404 com `status_code` 34 | Remova o ID da sua lista | | Chave ausente ou errada | 401 com `status_code` 7 | Pare e corrija a chave | | `overview` vazio | Uma string vazia | Peça de novo com `language=en-US` | | Nota desconhecida | `null` dentro de `ratings` | Oculte esse selo | | Sem data de lançamento | `release_date` vazio | Coloque o título por último | A lista completa de erros está em [erros](https://amodb.dev/pt/errors/). ## Como ficar dentro do limite de requisições Uma busca e uma chamada de detalhes custam uma requisição cada. Com 20 requisições por minuto são dez consultas de título por minuto, com 120 requisições por minuto são sessenta. Um acerto no cache de borda também conta, porque a verificação da chave e o limite de requisições rodam antes do cache. Mantenha um cache próprio para consultas repetidas e leia `X-RateLimit-Remaining` para ver quanto do minuto resta. Ao receber um 429, aguarde os segundos indicados em `Retry-After`. Os limites de cada plano estão em [limites de requisições](https://amodb.dev/pt/rate-limits/). ## Como se compara | Recurso | Scraping das páginas você mesmo | API de metadados com plano gratuito | amodb | | -------------------------------- | ------------------------------------- | -------------------------------------------- | ---------------------------------------------------- | | Formato da resposta | HTML que você precisa analisar | JSON | JSON no formato do TMDB v3 | | Estabilidade do esquema | Quebra quando o markup da página muda | Definida pelo provedor | Caminhos e campos fixos, novos campos podem aparecer | | Termos de acesso | Valem os termos de cada site | Plano gratuito com termos de uso, confira-os | Pago, pré-pago, sem plano gratuito | | Limite de requisições | Nada em que se possa confiar | Definido pelo provedor | 20, 40 ou 120 requisições por minuto por chave | | Avaliações de várias fontes | Um scraper por site | Varia, consulte a documentação | `ratings` na mesma chamada, null quando desconhecida | | Idiomas | O que cada página oferecer | Varia | 14, escolhidos com `language` | | Reuso de clientes TMDB v3 e OMDb | Não | Só se usar o mesmo protocolo | Sim, troque a URL base | ## Preços O acesso é pré-pago por 1, 3, 6, 12 ou 24 meses, com 0, 10, 20, 30 e 40 por cento de desconto nos períodos mais longos. Não há renovação automática nem plano gratuito. Todos os planos recebem todos os dados, e os planos diferem apenas no limite: 20, 40 ou 120 requisições por minuto. Escolha um em [preços](https://amodb.dev/pt/pricing/) e faça sua primeira chamada em poucos minutos. ## Perguntas e respostas ### Esta API de filmes é compatível com o TMDB? Sim, nos endpoints de leitura de que um app de filmes precisa. Caminhos, parâmetros de consulta e JSON seguem o TMDB v3 em https://api.amodb.dev/3, então você troca a URL base e usa sua chave do amodb. Os métodos de escrita de conta, sessão, avaliação e lista retornam 405 com status_code 37. Os feeds de changes, aggregate_credits e as consultas de credit e review retornam 404. ### Posso consultar um filme pelo ID do IMDb? Sim. Chame /3/find/tt0133093?external_source=imdb_id e leia movie_results, ou use o endpoint no estilo OMDb em /omdb/?i=tt0133093. Ambos aceitam a mesma chave das chamadas no estilo TMDB. ### Quantas requisições uma página de filme precisa? No máximo duas: uma busca para obter o ID e depois uma chamada /movie/{id} com append_to_response=credits,videos,ratings. Se você já guarda o ID, uma única requisição basta. ### Quais idiomas a API de filmes retorna? Catorze: inglês, russo, ucraniano, bielorrusso, chinês, português, búlgaro, hebraico, tcheco, romeno, francês, polonês, italiano e espanhol. Passe uma tag do TMDB como pt-BR em language. Qualquer outra tag volta para o inglês. ### Existe plano gratuito ou período de teste? Não. O acesso é pré-pago por 1, 3, 6, 12 ou 24 meses, com descontos de 0, 10, 20, 30 e 40 por cento. Não há renovação automática. Os planos de 20, 40 e 120 requisições por minuto estão na página de preços. ## 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. - [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. - [Buscar por ID externo](https://amodb.dev/pt/find-by-external-id/): Busque um filme, série ou pessoa por id do IMDb, TVDB, Wikidata ou Kinopoisk com o endpoint find do TMDB e leia ids externos e dados do Wikidata de um título. - [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. - [Alternativa à API do TMDB](https://amodb.dev/pt/tmdb-api-alternative/): Precisa de uma alternativa à API do TMDB? Veja termos, limites, idiomas e avaliações, e migre para uma API paga com a maioria dos caminhos de leitura da v3. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/movie-api/