Cómo obtener la clave API de TMDB y usar la API de The Movie Database

The Movie Database (TMDB) es un catálogo de películas, programas de televisión, elenco y arte, construido por la comunidad. Su API es gratuita para uso no comercial siempre que se acredite a TMDB, lo que la convierte en el punto de partida habitual en cualquier lista de APIs de películas gratuitas. El inconveniente es el proceso de incorporación: TMDB le proporciona dos credenciales diferentes, y la guía oficial de inicio asume que ya sabe cuál usar.

Esta guía cubre todo el camino: cuenta, solicitud de clave, clave v3 versus token de acceso de lectura v4, primeras llamadas de búsqueda y detalles en curl y Python, las mismas llamadas guardadas como prueba en Apidog, y los límites de tasa, reglas de atribución y errores que encontrará el primer día.

Lo que necesita antes de empezar

• Una cuenta de TMDB con una dirección de correo electrónico verificada. La API rechaza las cuentas no verificadas con un 401.
• Un navegador de escritorio. La documentación de TMDB dice que las páginas de registro de la API no están optimizadas para dispositivos móviles.
• curl, o Python 3 con el paquete requests.
• Apidog, para almacenar el token de forma segura y guardar las solicitudes. Descargue Apidog para macOS, Windows o Linux.

Paso 1: crear una cuenta de TMDB

Vaya a themoviedb.org, haga clic en "Unirse a TMDB" y regístrese con una dirección de correo electrónico. Abra el correo electrónico de verificación y confírmelo antes de tocar la configuración de la API. Si lo omite, más tarde encontrará un confuso 401, código de estado 32: "Correo electrónico no verificado: Su dirección de correo electrónico no ha sido verificada."

Paso 2: solicitar la clave API

Una vez que haya iniciado sesión, abra la configuración de su cuenta y haga clic en "API" en la barra lateral izquierda. La FAQ de TMDB describe esta como la única ruta: "Puede solicitar una clave API haciendo clic en el enlace 'API' desde la barra lateral izquierda dentro de la página de configuración de su cuenta."

Aceptará los términos de uso de la API, luego completará una breve solicitud: lo que está construyendo, una URL si tiene una, un resumen de cómo usará los datos y el tipo de uso. Elija la opción de desarrollador para proyectos personales, prototipos y herramientas internas. TMDB considera un proyecto comercial "si el propósito principal es generar ingresos en beneficio del propietario", y ese camino requiere un acuerdo por escrito con su equipo de ventas.

Después de enviar, la misma página de configuración muestra dos credenciales:

• Clave API, etiquetada para autenticación v3. Una cadena hexadecimal de 32 caracteres.
• Token de acceso de lectura de la API, una cadena mucho más larga estilo JWT.

TMDB no publica una línea de tiempo de revisión; en la práctica, ambos valores aparecen tan pronto como se envía el formulario. Trátelos como cualquier otro secreto y manténgalos fuera de commits, ventanas de chat y capturas de pantalla.

Clave API v3 vs. token de acceso de lectura v4

Las dos credenciales no son "antigua" y "nueva". Son dos formas de identificar la misma aplicación, y la documentación oficial de autenticación establece que ambas "proporcionan el mismo nivel de acceso".

La propia recomendación de TMDB es el token Bearer: "El método predeterminado para autenticarse es con su token de acceso", y "tiene el beneficio adicional de ser un proceso de autenticación único que puede usar tanto con los métodos v3 como v4".

Use la cabecera Bearer a menos que su cliente no pueda establecer cabeceras. Mantener la credencial fuera de la URL es el mismo argumento detrás de cualquier decisión de clave API versus token Bearer: las URLs se registran, se almacenan en caché y se comparten.

Una distinción más. Todo en este artículo son datos de catálogo de solo lectura, que solo necesitan la credencial de la aplicación. La API v4 añade funciones de cuenta como listas, favoritos, calificaciones y listas de seguimiento. Escribir en estos para un usuario de TMDB requiere un "handshake" adicional: un token de solicitud de /4/auth/request_token, la aprobación del usuario, y luego un token de acceso del usuario de /4/auth/access_token. Nada de esto es necesario para buscar películas o leer detalles.

Paso 3: haga su primera solicitud

Todas las llamadas v3 van a https://api.themoviedb.org/3. Dos endpoints cubren la mayoría de los primeros proyectos: buscar por título, luego obtener detalles por ID.

Buscar una película con 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 TU_TOKEN_DE_ACCESO_DE_LECTURA' \
  --header 'accept: application/json'

La respuesta es un objeto de página con page, results, total_pages y total_results. Cada resultado contiene id, title, release_date, overview, poster_path, genre_ids y vote_average. En el propio ejemplo de búsqueda de TMDB, el primer resultado para "fight club" es el ID 550, lanzado el 15-10-1999.

La misma llamada con la clave v3 se ve así. Tenga en cuenta que no hay ninguna cabecera de autenticación:

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

Obtener detalles de películas con Python

Ahora, tome el ID de la búsqueda y solicite el registro completo. El endpoint de detalles de películas devuelve runtime, genres, budget, revenue y overview. Su parámetro append_to_response añade subrecursos como créditos al mismo viaje de ida y vuelta, hasta 20 por solicitud.

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"])

La última línea es la parte que la gente omite. poster_path es solo una ruta. Como explica la guía de conceptos básicos de imágenes, una URL que funciona es https://image.tmdb.org/t/p/, luego un tamaño como w500 u original, y luego la ruta. /3/configuration enumera todos los tamaños válidos.

Paso 4: ejecutar y guardar las solicitudes en Apidog

Una vez que las llamadas en bruto funcionen, muévalas a un lugar donde no las pierda. En Apidog, esto lleva unos minutos y le deja una prueba guardada y compartible.

1. Cree un proyecto y añada un entorno llamado "TMDB" con dos variables: base_url establecida en https://api.themoviedb.org/3, y tmdb_token conteniendo su token de acceso de lectura. Marque el token como secreto para que quede enmascarado en la interfaz de usuario y no se incluya en las exportaciones; la guía sobre variables de entorno y secretas cubre las opciones.
2. Añada una solicitud GET a {{base_url}}/search/movie con un parámetro query. En la pestaña Auth, elija Bearer Token e introduzca {{tmdb_token}}. Envíela y confirme que obtiene un 200 y un array de results.
3. Añada una segunda solicitud GET a {{base_url}}/movie/{{movie_id}}. En el posprocesador de la primera solicitud, extraiga results[0].id en movie_id para que la segunda llamada siempre siga a la primera.
4. Guarde ambas como un escenario de prueba con aserciones: el estado es igual a 200, total_results es mayor que 0, y title en la respuesta de detalles no está vacío. Ejecútelo cada vez que cambie la integración.

¿Está construyendo un frontend con estos datos? Active el servidor simulado para el endpoint de búsqueda. Apidog genera una respuesta que coincide con el esquema, para que el equipo de UI pueda construir la cuadrícula de pósteres sin un token en vivo o solicitudes reales contra los límites de TMDB.

Límites de tasa y reglas de atribución

Todo lo que sigue se cita de la documentación de TMDB.

Límites de tasa. La página de límites de tasa de TMDB dice que el límite original de 40 solicitudes cada 10 segundos fue deshabilitado el 16 de diciembre de 2019. Los límites superiores se mantienen "para ayudar a mitigar el raspado masivo innecesariamente alto", y "se sitúan en el rango de 40 solicitudes por segundo". Esa cifra puede cambiar sin previo aviso, así que respete cualquier HTTP 429, espere un tiempo y vuelva a intentarlo.

Costo. De la FAQ: "Nuestra API es de uso gratuito para fines no comerciales siempre que atribuya a TMDB como la fuente de los datos y/o imágenes." Los proyectos comerciales deben contactar a sales@themoviedb.org.

Atribución. Muestre el logotipo de TMDB y este aviso en su aplicación: "Este producto utiliza la API de TMDB pero no está respaldado ni certificado por TMDB." Los términos de uso de la API utilizan una redacción ligeramente más larga y requieren que el logotipo sea menos prominente que su propia marca, y nunca se recoloree, estire, voltee o rote.

Almacenamiento en caché. Los términos prohíben almacenar en caché cualquier dato de TMDB por más de seis meses. Guarde lo que necesite, pero planifique una actualización.

Sin SLA. TMDB lo dice claramente. Implemente tiempos de espera y reintentos.

Higiene de la clave. Ambas credenciales deben ir en variables de entorno o en un administrador de secretos, nunca en el código fuente. Si una termina en un repositorio, rótela desde la página de configuración y realice una verificación de fugas de claves API en su historial.

Errores comunes y qué significan

TMDB devuelve un cuerpo JSON con status_code y status_message junto con el estado HTTP. La referencia de errores enumera docenas de códigos; estos son los que verá primero.

Preguntas frecuentes

¿La clave API de TMDB es gratuita?

Sí, para uso no comercial con atribución. No existe un nivel de autoservicio de pago. Si su proyecto genera ingresos, TMDB le pide que organice un acuerdo comercial a través de su equipo de ventas.

¿Debo usar la clave API o el token de acceso de lectura?

Use el token de acceso de lectura como cabecera Bearer. TMDB lo llama el predeterminado, funciona tanto en v3 como en v4, y se mantiene fuera de sus URLs. La clave v3 existe para herramientas que solo pueden enviar parámetros de consulta. Si el concepto es nuevo, este manual sobre qué es una clave API explica el modelo que sigue TMDB.

¿Puedo llamar a TMDB directamente desde un navegador o una aplicación móvil?

Puede, pero cualquier cosa enviada al cliente es pública, incluido su token. Para un proyecto personal, es un riesgo aceptado. Para cualquier cosa con usuarios, coloque un pequeño backend o una función sin servidor delante de TMDB, mantenga el token allí y almacene en caché las consultas populares.

¿Cuál es la diferencia entre v3 y v4?

v3 es el catálogo: búsqueda, detalles de películas y TV, personas, imágenes, descubrimiento. v4 cubre funciones de cuenta como listas, favoritos, calificaciones y listas de seguimiento, y sus endpoints de escritura requieren un token de acceso de usuario. Su token de acceso de lectura autentica contra ambos.

Adónde ir desde aquí

Ahora tiene una clave API de TMDB funcional, una regla para qué credencial enviar, un flujo de búsqueda y detalles en curl y Python, y el mismo flujo guardado como un escenario de prueba de Apidog. A continuación, añada discover/movie para la navegación filtrada y coloque el aviso de atribución en su aplicación antes de compartirla. Todo lo demás en el catálogo utiliza la misma URL base, cabecera Bearer y formatos de error.