如何获取 TMDB API Key 并查询 The Movie Database

The Movie Database（TMDB）是一个由社区共建的电影、剧集、演职人员和图片素材目录。只要署名 TMDB，它的 API 就能免费用于非商业用途，这也让它成为各类免费影视 API 清单通常的起点。麻烦之处在于上手流程：TMDB 会给你两套不同的凭据，而官方 getting started 指南默认你已经知道该用哪一个。

本文覆盖完整路径：注册账号、申请 key、v3 key 与 v4 读访问 Token 的对比、用 curl 和 Python 发起第一次搜索与详情调用、把同样的调用保存为 Apifox 中的测试，以及你第一天就会遇到的速率限制、署名规则和错误。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始之前需要准备什么

• 一个邮箱已验证的 TMDB 账号。未验证的账号会被 API 以 401 拒绝。
• 桌面浏览器。TMDB 的文档说明 API 注册页面没有针对移动设备优化。
• curl，或者带 requests 包的 Python 3。
• Apifox，用来安全保存 token 并留存这些请求。

第 1 步：创建 TMDB 账号

访问 themoviedb.org，点击 “Join TMDB”，用邮箱注册。在动 API 设置之前，先打开验证邮件完成确认。跳过这一步，之后就会撞上一个让人摸不着头脑的 401，状态码 32：“Email not verified: Your email address has not been verified.”

第 2 步：申请 API Key

登录后打开账号设置，点击左侧边栏中的 “API”。TMDB 的 FAQ 说明这是唯一途径：“你可以在账号设置页面里，点击左侧边栏的 ‘API’ 链接来申请 API key。”

你需要接受 API 使用条款，然后填写一份简短申请：你在做什么、有没有网址、打算如何使用这些数据，以及使用类型。个人项目、原型和内部工具选择 developer 选项。只要“主要目的是为所有者创造收入”，TMDB 就把项目算作商业用途，这条路径需要与其销售团队签订书面协议。

提交之后，同一个设置页面会显示两套凭据：

• API Key，标注用于 v3 认证。32 个字符的十六进制字符串。
• API Read Access Token，一个长很多的 JWT 风格字符串。

TMDB 没有公布审核时长；实际上表单提交通过后这两个值就会立即出现。把它们当作其他任何密钥一样对待，不要写进提交、聊天窗口和截图里。

v3 API Key 与 v4 读访问 Token 的对比

这两套凭据不是“旧”与“新”的关系，而是标识同一个应用的两种方式。官方 认证文档指出，两者“提供相同级别的访问权限”。

TMDB 自己推荐的是 Bearer token：“默认的认证方式就是使用你的 access token”，而且它“还有一个好处：同一套认证流程可以同时用于 v3 和 v4 两种方式”。

除非你的客户端无法设置 header，否则都用 Bearer header。把凭据放在 URL 之外，和所有 API Key 与 Bearer token 之争背后的理由一样：URL 会被记录、缓存和分享。

还有一点区别。本文涉及的一切都是只读的目录数据，只需要应用凭据。v4 API 增加了列表、收藏、评分、想看清单等账号功能。以 TMDB 用户身份写入这些数据需要额外的握手：先从 /4/auth/request_token 拿到 request token，经用户批准，再从 /4/auth/access_token 换取 user access token。搜索电影或读取详情都不需要这些。

第 3 步：发起第一个请求

所有 v3 调用都发往 https://api.themoviedb.org/3。多数入门项目只需要两个接口：按标题搜索，再按 id 获取详情。

用 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'

响应是一个分页对象，包含 page、results、total_pages 和 total_results。每条结果带有 id、title、release_date、overview、poster_path、genre_ids 和 vote_average。在 TMDB 自己的 搜索示例中，“fight club” 的第一条命中是 id 550，上映日期 1999-10-15。

用 v3 key 发同一个调用是这样，注意完全没有认证 header：

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

用 Python 获取电影详情

现在拿搜索结果里的 id 去取完整记录。movie details 接口会返回 runtime、genres、budget、revenue 和 overview。它的 append_to_response 参数可以在同一次往返里附带 credits 等子资源，每个请求最多 20 个。

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

最后一行是很多人会漏掉的地方。poster_path 只是一个路径。正如 图片基础指南所解释的，可用的 URL 由 https://image.tmdb.org/t/p/、尺寸（如 w500 或 original）和路径拼成。/3/configuration 列出了所有可用尺寸。

第 4 步：在 Apifox 中运行并保存请求

原始调用跑通之后，把它们挪到不会丢的地方。在 Apifox 里这只需几分钟，你就能得到一个可保存、可分享的测试。

1. 新建项目，添加一个名为 “TMDB” 的环境，里面有两个变量：base_url 设为 https://api.themoviedb.org/3，tmdb_token 保存你的读访问 Token。把该 token 标记为 secret，这样它会在界面上被遮蔽，也不会进入导出内容；环境变量与 secret 变量的指南介绍了各种选项。
2. 添加一个 GET 请求 {{base_url}}/search/movie，带一个 query 参数。在 Auth 标签页选择 Bearer Token，填入 {{tmdb_token}}。发送，确认返回 200 和一个 results 数组。
3. 再添加一个 GET 请求 {{base_url}}/movie/{{movie_id}}。在第一个请求的后置处理器中把 results[0].id 提取到 movie_id，让第二个调用总是跟在第一个之后。
4. 把两者保存为带断言的测试场景：状态码等于 200、total_results 大于 0、详情响应中的 title 非空。集成有变动时就运行它。

要用这些数据做前端？给搜索接口打开 mock 服务。Apifox 会生成符合数据模型的响应，这样 UI 团队不需要真实 token，也不用向 TMDB 发真实请求去撞速率限制，就能把海报墙做出来。

速率限制与署名规则

以下内容均引自 TMDB 的文档。

速率限制。TMDB 的 速率限制页面说明，最初每 10 秒 40 次请求的限制已于 2019 年 12 月 16 日取消。上限依然存在，是“为了缓解毫无必要的高强度批量抓取”，并且“大致落在每秒 40 次请求这个区间”。这个数字可能随时变化，所以遇到 HTTP 429 要遵守、退避并重试。

费用。FAQ 中写道：“只要署名 TMDB 为数据和/或图片来源，我们的 API 即可免费用于非商业用途。”商业项目必须联系 sales@themoviedb.org。

署名。在你的应用中展示 TMDB 徽标和这段声明：“This product uses the TMDB API but is not endorsed or certified by TMDB.” API 使用条款的措辞稍长，并要求徽标的醒目程度低于你自己的品牌，且不得改色、拉伸、翻转或旋转。

缓存。条款禁止将任何 TMDB 数据缓存超过六个月。按需存储，但要做好刷新计划。

没有 SLA。TMDB 明确表示如此。请加入超时和重试。

Key 安全习惯。两套凭据都应放在环境变量或密钥管理器中，绝不能写进源码。如果某个凭据进了仓库，请在设置页面轮换它，并对你的历史记录做一次 API Key 泄露检查。

常见错误及其含义

TMDB 在 HTTP 状态之外，还会返回带 status_code 和 status_message 的 JSON body。错误参考列出了几十个错误码；以下是你最先会遇到的几个。

常见问题

TMDB API Key 是免费的吗？

是，非商业用途加署名即可。没有付费自助套餐。如果你的项目有收入，TMDB 要求你通过其销售团队签订商业协议。

应该用 API Key 还是读访问 Token？

用读访问 Token，放在 Bearer header 里。TMDB 把它称为默认方式，它在 v3 和 v4 上都可用，而且不会出现在 URL 中。v3 key 是为那些只能发送 query 参数的工具保留的。如果这个概念对你来说还很陌生，这篇介绍 API Key 是什么的入门文章解释了 TMDB 采用的模式。

可以直接从浏览器或移动应用调用 TMDB 吗？

可以，但任何交付到客户端的东西都是公开的，包括你的 token。对个人项目来说，这是可以接受的风险。只要涉及用户，就应该在 TMDB 前面放一个小型后端或无服务器函数，把 token 放在那里，并缓存热门查询。

v3 和 v4 有什么区别？

v3 是目录：搜索、电影和剧集详情、人物、图片、发现。v4 覆盖列表、收藏、评分、想看清单等账号功能，其写入接口需要 user access token。你的读访问 Token 可以同时通过两者的认证。

接下来做什么

你现在已经有一个可用的 TMDB API key、判断该发哪套凭据的规则、用 curl 和 Python 实现的先搜索后详情流程，以及保存为 Apifox 测试场景的同样流程。接下来可以加上 discover/movie 做筛选浏览，并在分享之前把署名声明放进你的应用。目录中的其他内容都使用相同的前置 URL、Bearer header 和错误结构。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名