tmdb

在终端中获取 TMDb 元数据

设置

在 TMDb API 设置中创建凭据。建议使用 API Read Access Token：

export TMDB_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
# Or use the v3 key: export TMDB_API_KEY="YOUR_API_KEY"

CLI 会发送 Authorization: Bearer $TMDB_ACCESS_TOKEN 或 ?api_key=$TMDB_API_KEY。这两种形式的 v3 访问级别相同；只需配置其中一种。--help 和 --dry-run 无需凭据。

基本命令

搜索和识别

tmdb movie search --term "dune" --limit 5 --json
tmdb tv search --term "severance" --limit 5
tmdb find tt0111161 --source imdb_id --json

--source 接受官方外部来源值：imdb_id、facebook_id、instagram_id、tvdb_id、tiktok_id、twitter_id、wikidata_id 和 youtube_id。不支持 Freebase 查询：已弃用的 freebase_mid 和 freebase_id 值会被拒绝。响应分为 movie_results、tv_results、person_results、tv_season_results 和 tv_episode_results。

详情和扩充

tmdb movie detail 550 --append credits,videos --json
tmdb movie detail 550 --append 'credits,watch/providers,external_ids' --json

复合响应会将请求的名称用作顶层键。构造原始 URL 时，请对 watch/providers 中的斜杠进行编码。

发现和浏览

tmdb movie discover --genre horror --rating 7 --limit 10
tmdb movie discover --genre horror --certification R --from 2024-01-01 --to 2024-12-31
tmdb trending --type all --window week --limit 20 --json
tmdb genre list --type movie --json
tmdb genre list --type tv --json
tmdb certification --json

在原始 discover 请求中，将 vote_count.gte 与 vote_average.desc 搭配使用，避免投票数很少的标题占据前列。根据 TMDb 当前文档，逗号分隔的流派 ID 表示 AND，竖线分隔的 ID 表示 OR。

工作流示例

从 IMDb ID 获取扩充后的电影信息

1. 解析 IMDb 标识符：

curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN" \
  'https://api.themoviedb.org/3/find/tt0111161?external_source=imdb_id' > /tmp/find.json
id=$(jq -r '.movie_results[0].id' /tmp/find.json)

2. 获取详情和复合资源：

curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN" \
  "https://api.themoviedb.org/3/movie/$id?append_to_response=credits,videos,watch%2Fproviders" \
  | jq '{title, runtime, director: [.credits.crew[] | select(.job == "Director") | .name], cast: [.credits.cast[0:5][].name], providers: .["watch/providers"].results.US}'

先搜索，再获取详情

tmdb movie search --term "dune" --limit 1 --json > /tmp/search.json
id=$(jq -r '.results[0].id' /tmp/search.json)
tmdb movie detail "$id" --append recommendations,similar --json

筛选可靠的发现结果

直接使用 API 时，请组合使用日期范围、竖线 OR 或逗号 AND 流派表达式、vote_count.gte 和 sort_by=vote_average.desc。然后使用 jq 仅保留下一工作流步骤所需的字段。

JSON 和 jq

将 --json 放在子命令之前或之后均可。JSON 搜索输出包含 results，通常还包含分页字段 page、total_pages 和 total_results；服务将页码限制为 500。使用 jq -r '.results[] | [.id, (.title // .name)] | @tsv' 可稳定地传递表格数据。

已知注意事项

• 凭据的二选一： api_key 和 Bearer 是替代选项，不能混用。凭据被拒绝时，通常会返回 HTTP 401、status_code: 7 和 Invalid API key: You must be granted a valid key.。权限错误使用代码 3。代码 33 表示请求令牌无效，而不是此 API 密钥错误。
• 分页上限： 页码从 1 开始，最高为 500；超过上限的请求会失败。即使总数看起来更大，搜索和发现结果实际上也最多只能访问 10,000 条。速率建议约为每秒 40 个请求；收到 429 响应时应遵循 Retry-After。
• 复合语法： 追加值以逗号分隔，最多限 20 次调用。watch/providers 中包含斜杠，因此在 curl 中应对其进行 URL 编码，并使用 jq 的 .\"watch/providers\" 表示法。
• 外部 ID 的结构： /find/ 不会返回一个通用的 id；选择电影或电视详情前，请检查相应的嵌套数组。只有文档列出的 8 个 external_source 值有效；已弃用的 Freebase 来源（freebase_mid、freebase_id）会被拒绝。
• 提供商筛选条件： with_watch_providers 必须搭配 watch_region 使用；提供商数据须遵守 JustWatch 的署名要求。
• 本地化和图片： 需要确保结果可复现时，请使用 language=en-US 和市场 region。图片 URL 由 /3/configuration 中的安全基础 URL、有效尺寸和返回的路径构成。

适用场景

此技能适用于只读的电影和电视元数据发现，包括演职人员、发行信息、分级、图片、推荐内容和提供商元数据。

不适用场景

请勿将其用于种子或盗版搜索、播放或下载流媒体，或维护个人已观看／未观看状态。观看历史工作流请使用 trakt，可用性操作请使用播放／目录集成。

参考文件

文件	用途
references/auth-pagination-and-errors.md	凭据、分页、速率限制、错误、语言、地区和图片
references/find-and-details.md	IMDb/TVDB 查找、响应映射、详情字段、复合请求
references/search-discover-trending.md	搜索、发现筛选条件、趋势、类型、分级和上映列表

可用脚本和先决条件

• scripts/tmdb 是一个可执行的 Python 命令行工具，仅使用标准库和 requests；支持 --json、--dry-run、--quiet 和 --verbose。
• scripts/test_tmdb.py 是一个离线 unittest/pytest 测试套件；所有 HTTP 行为均为模拟。
• 需要 Python 3.8+ 和 requests。此技能不会启动任何服务。