Como Obter uma Chave API TMDB e Consultar a API The Movie Database

O The Movie Database (TMDB) é um catálogo construído pela comunidade de filmes, programas de TV, elenco e artes visuais. Sua API é gratuita para uso não comercial, desde que você credite o TMDB, o que a torna o ponto de partida comum em qualquer lista de APIs de filmes gratuitas. O problema está na integração: o TMDB oferece duas credenciais diferentes, e o guia oficial de primeiros passos assume que você já sabe qual usar.

Este guia cobre todo o caminho: conta, solicitação de chave, chave v3 versus token de acesso de leitura v4, primeiras chamadas de busca e detalhes em curl e Python, as mesmas chamadas salvas como um teste no Apidog, e os limites de taxa, regras de atribuição e erros que você encontrará no primeiro dia.

O que você precisa antes de começar

• Uma conta TMDB com um endereço de e-mail verificado. A API recusa contas não verificadas com um 401.
• Um navegador de desktop. Os documentos do TMDB afirmam que as páginas de registro da API não são otimizadas para dispositivos móveis.
• curl, ou Python 3 com o pacote requests.
• Apidog, para armazenar o token com segurança e manter as requisições. Baixe o Apidog para macOS, Windows ou Linux.

Passo 1: crie uma conta TMDB

Vá para themoviedb.org, clique em “Join TMDB” (Junte-se ao TMDB) e cadastre-se com um endereço de e-mail. Abra o e-mail de verificação e confirme-o antes de mexer nas configurações da API. Se você pular esta etapa, encontrará um confuso erro 401 mais tarde, código de status 32: “Email not verified: Your email address has not been verified.” (E-mail não verificado: Seu endereço de e-mail não foi verificado.)

Passo 2: solicite a chave da API

Depois de fazer login, abra as configurações da sua conta e clique em “API” na barra lateral esquerda. O FAQ do TMDB descreve esta como a única rota: “Você pode solicitar uma chave de API clicando no link ‘API’ na barra lateral esquerda da página de configurações da sua conta.”

Você aceitará os termos de uso da API e, em seguida, preencherá um breve formulário: o que você está construindo, uma URL se tiver uma, um resumo de como usará os dados e o tipo de uso. Escolha a opção de desenvolvedor para projetos pessoais, protótipos e ferramentas internas. O TMDB considera um projeto comercial “se o objetivo principal for gerar receita para o benefício do proprietário”, e esse caminho exige um acordo por escrito com a equipe de vendas.

Após o envio, a mesma página de configurações exibe duas credenciais:

• Chave da API (API Key), rotulada para autenticação v3. Uma string hexadecimal de 32 caracteres.
• Token de Acesso de Leitura da API (API Read Access Token), uma string no estilo JWT muito mais longa.

O TMDB não publica um cronograma de revisão; na prática, ambos os valores aparecem assim que o formulário é processado. Trate-os como qualquer outro segredo e mantenha-os fora de commits, janelas de chat e capturas de tela.

Chave da API v3 vs. token de acesso de leitura v4

As duas credenciais não são “antigas” e “novas”. São duas formas de identificar a mesma aplicação, e a documentação oficial de autenticação afirma que ambas “fornecem o mesmo nível de acesso”.

A própria recomendação do TMDB é o token Bearer: “O método padrão para autenticar é com seu token de acesso,” e ele “tem o benefício adicional de ser um único processo de autenticação que você pode usar tanto nos métodos v3 quanto v4.”

Use o cabeçalho Bearer, a menos que seu cliente não possa definir cabeçalhos. Manter a credencial fora da URL é o mesmo argumento por trás de qualquer decisão entre chave da API versus token Bearer: URLs são registradas, armazenadas em cache e compartilhadas.

Mais uma distinção. Tudo neste artigo são dados de catálogo somente leitura, que precisam apenas da credencial da aplicação. A API v4 adiciona recursos de conta, como listas, favoritos, avaliações e listas de observação. Gravar nesses recursos para um usuário TMDB requer um handshake adicional: um token de solicitação de /4/auth/request_token, aprovação do usuário e, em seguida, um token de acesso do usuário de /4/auth/access_token. Nada disso é necessário para pesquisar filmes ou ler detalhes.

Passo 3: faça sua primeira requisição

Todas as chamadas v3 vão para https://api.themoviedb.org/3. Dois endpoints cobrem a maioria dos primeiros projetos: busca por título e, em seguida, busca de detalhes por ID.

Buscar um filme com curl

curl --request GET \
  --url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
  --header 'Authorization: Bearer YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

A resposta é um objeto de página com page, results, total_pages e total_results. Cada resultado contém id, title, release_date, overview, poster_path, genre_ids e vote_average. No exemplo de busca do próprio TMDB, o primeiro resultado para “fight club” é o ID 550, lançado em 15/10/1999.

A mesma chamada com a chave v3 se parece com isso. Note que não há nenhum cabeçalho de autenticação:

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

Obter detalhes do filme com Python

Agora, pegue o ID da busca e solicite o registro completo. O endpoint de detalhes do filme retorna runtime, genres, budget, revenue e overview. Seu parâmetro append_to_response adiciona sub-recursos como créditos na mesma viagem de ida e volta, até 20 por requisição.

import os
import requests

TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}


def search_movie(title):
    r = requests.get(
        f"{BASE}/search/movie",
        params={"query": title, "include_adult": "false", "language": "en-US"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]


def movie_details(movie_id):
    r = requests.get(
        f"{BASE}/movie/{movie_id}",
        params={"append_to_response": "credits"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])

A última linha é a parte que as pessoas esquecem. poster_path é apenas um caminho. Como o guia de noções básicas de imagem explica, uma URL funcional é https://image.tmdb.org/t/p/, seguida de um tamanho como w500 ou original, e então o caminho. /3/configuration lista todos os tamanhos válidos.

Passo 4: execute e salve as requisições no Apidog

Assim que as chamadas brutas funcionarem, mova-as para um local onde você não as perderá. No Apidog, isso leva alguns minutos e deixa você com um teste salvo e compartilhável.

1. Crie um projeto e adicione um ambiente chamado “TMDB” com duas variáveis: base_url definida como https://api.themoviedb.org/3, e tmdb_token contendo seu token de acesso de leitura. Marque o token como secreto para que ele seja mascarado na interface do usuário e não seja exportado; o guia sobre variáveis de ambiente e secretas cobre as opções.
2. Adicione uma requisição GET para {{base_url}}/search/movie com um parâmetro query. Na aba Auth, escolha Bearer Token e insira {{tmdb_token}}. Envie e confirme que você recebe um 200 e um array results.
3. Adicione uma segunda requisição GET para {{base_url}}/movie/{{movie_id}}. No pós-processador da primeira requisição, extraia results[0].id para movie_id para que a segunda chamada sempre siga a primeira.
4. Salve ambos como um cenário de teste com asserções: status igual a 200, total_results maior que 0, e title na resposta de detalhes não vazio. Execute-o sempre que a integração mudar.

Construindo um frontend com base nesses dados? Ative o mock server para o endpoint de busca. O Apidog gera uma resposta que corresponde ao esquema, para que a equipe de UI possa construir a grade de pôsteres sem um token ativo ou requisições reais contra os limites do TMDB.

Limites de taxa e regras de atribuição

Tudo abaixo é citado dos documentos do TMDB.

Limites de taxa. A página de limites de taxa do TMDB afirma que o limite original de 40 requisições a cada 10 segundos foi desativado em 16 de dezembro de 2019. Os limites superiores permanecem “para ajudar a mitigar raspagens em massa desnecessariamente altas”, e eles “situam-se em torno de 40 requisições por segundo.” Esse valor pode mudar sem aviso, então respeite qualquer HTTP 429, espere e tente novamente.

Custo. Do FAQ: “Nossa API é gratuita para uso não comercial, desde que você atribua o TMDB como a fonte dos dados e/ou imagens.” Projetos comerciais devem entrar em contato com sales@themoviedb.org.

Atribuição. Exiba o logotipo do TMDB e este aviso em sua aplicação: “Este produto usa a API do TMDB, mas não é endossado ou certificado pelo TMDB.” Os termos de uso da API usam uma redação ligeiramente mais longa e exigem que o logotipo seja menos proeminente do que sua própria marca, e nunca seja recolorido, esticado, invertido ou girado.

Cache. Os termos proíbem o cache de quaisquer dados do TMDB por mais de seis meses. Armazene o que você precisa, mas planeje uma atualização.

Sem SLA. O TMDB afirma isso claramente. Implemente timeouts e retentativas.

Higiene da chave. Ambas as credenciais devem estar em variáveis de ambiente ou em um gerenciador de segredos, nunca no código-fonte. Se uma acabar em um repositório, gire-a na página de configurações e execute uma verificação de vazamento de chave da API em seu histórico.

Erros comuns e o que eles significam

O TMDB retorna um corpo JSON com status_code e status_message junto com o status HTTP. A referência de erros lista dezenas de códigos; estes são os que você verá primeiro.

FAQ

A chave da API do TMDB é gratuita?

Sim, para uso não comercial com atribuição. Não há um nível de serviço pago. Se o seu projeto gerar receita, o TMDB pede que você providencie um acordo comercial através de sua equipe de vendas.

Devo usar a chave da API ou o token de acesso de leitura?

Use o token de acesso de leitura como um cabeçalho Bearer. O TMDB o chama de padrão, ele funciona tanto na v3 quanto na v4, e ele fica fora das suas URLs. A chave v3 existe para ferramentas que só podem enviar parâmetros de consulta. Se o conceito é novo, este guia sobre o que é uma chave de API explica o modelo que o TMDB segue.

Posso chamar o TMDB diretamente de um navegador ou aplicativo móvel?

Você pode, mas qualquer coisa enviada ao cliente é pública, incluindo seu token. Para um projeto pessoal, isso é um risco aceito. Para qualquer coisa com usuários, coloque um pequeno backend ou função serverless na frente do TMDB, mantenha o token lá e armazene em cache as consultas populares.

Qual a diferença entre v3 e v4?

A v3 é o catálogo: busca, detalhes de filmes e TV, pessoas, imagens, descoberta. A v4 cobre recursos de conta como listas, favoritos, classificações e listas de observação, e seus endpoints de escrita exigem um token de acesso do usuário. Seu token de acesso de leitura autentica contra ambos.

Para onde ir a partir daqui

Agora você tem uma chave de API do TMDB funcional, uma regra sobre qual credencial enviar, um fluxo de busca e detalhes em curl e Python, e o mesmo fluxo salvo como um cenário de teste no Apidog. Em seguida, adicione discover/movie para navegação filtrada e coloque o aviso de atribuição em seu aplicativo antes de compartilhá-lo. Todo o resto no catálogo usa a mesma URL base, cabeçalho Bearer e formatos de erro.