原文来源：https://www.tvmaze.com/api（TVmaze 官方公共 API 文档）
整理日期：2026-11-08
说明：第一至四章为官方页面逐条翻译与结构化整理；标注「补充」的章节（第五章响应字段、第六章实践建议、以及各处「实测」标注）来自对 https://api.tvmaze.com 的实际请求，不属于官方文档原文，仅供参考。
术语约定：show 译为剧集（一部剧/节目），episode 译为分集（一集），season 译为季，Network 译为电视网，Web Channel 译为网络频道（流媒体平台）。

---

一、快速了解

TVmaze 提供一套免费、快速、简洁的 REST API，返回 JSON，遵循 HATEOAS 与 HAL 设计原则（资源自带 _links 链接，可用 embed 把关联资源一次性嵌入响应）。

三个最小可用示例：

# 按名字搜剧
curl "https://api.tvmaze.com/search/shows?q=girls"

# 取某部剧的主信息，并把分集列表一起嵌入
curl "https://api.tvmaze.com/shows/1?embed=episodes"

# 查某天某国的播出日程
curl "https://api.tvmaze.com/schedule?country=US&date=2020-05-29"

1.1 通用约定

• 占位符：文档 URL 中 :id、:query、:num、:date、:countrycode 等均需替换为实际值，冒号本身不属于路径。
• 完整 URL = https://api.tvmaze.com + 文档给出的路径，例如 /shows/:id → https://api.tvmaze.com/shows/1。
• HTTP 方法：公共 API 全部为只读 GET。
• 日期格式：ISO 8601，如 2020-05-29。
• 国家码：ISO 3166-1 两位码，如 US、GB。注意：英国的官方码是 GB，不是 UK。
• 空值：字段无数据时返回 null（JSON），而不是空字符串或被省略。例如未配图时 image: null。
• 外部 ID：imdb、thetvdb、tvrage 三种 ID 均可用于 lookup 查询（实测三者都支持）。

1.2 常见状态码

---

二、端点速查表

所有端点均为 GET，下表路径均省略根地址 https://api.tvmaze.com。

搜索 Search

播出日程 Schedule

剧集 Shows

分集 Episodes

人物 People

更新 Updates

---

三、端点详解

3.1 搜索 Search

3.1.1 剧集搜索 Show search

用途：按剧名在 TVmaze 全库搜索。采用模糊算法（容错度 fuzziness = 2），查询词里有小笔误也能命中；结果按相关度排序（最匹配的在最前），每条都包含该剧的完整信息。

典型场景：建立「剧名 → TVmaze ID」的本地映射时，把候选列表展示给最终用户挑选，避免匹配到同名但不同的剧；选定后本地保存该剧 ID 或 URL，后续请求直接走该剧 URL。

注意：普通搜索不支持 embed，只有下面单一搜索支持。

3.1.2 剧集单一搜索 Show single search

用途：不想让用户做二次选择、希望输入后直接出结果时用。该端点要么只返回一个结果，要么不返回任何结果。同样容忍笔误，但容错度更低（fuzziness = 1，普通搜索是 2），以降低误命中概率。

与搜索端点不同：单一搜索支持 embed 嵌入附加信息（见嵌入）。

易踩坑：若存在多部完全同名的剧（例如 Top Gear），本端点返回哪一部是未定义的。需要精确匹配时请改用 /search/shows。

3.1.3 剧集外部 ID 查找 Show Lookup

用途：已知某剧在 TheTVDB / IMDb / TVRage 的 ID，反查它在 TVmaze 中的对应剧集。匹配成功返回 HTTP 301 重定向到该剧 URL；匹配失败返回 HTTP 404。

实测：imdb=tt0944947 → 301 跳转到 /shows/82；thetvdb=81189 → /shows/169；tvrage=24493 → /shows/82；不存在的 ID → 404。
开发时记得让 HTTP 客户端允许跟随重定向，否则只会拿到 301。

3.1.4 人物搜索 People search

用途：按姓名搜索全库人物，机制与剧集搜索相同。

---

3.2 播出日程 Schedule

总览：日程是「某国家、某日期播出的全部分集」的完整列表，按实际播出顺序返回，每条都包含分集与所属剧集的完整信息。

注意：两个边界：

• 只返回与具体国家绑定的分集——通过电视网（Network）或本地网络频道（如 HBO Max、Sky Go）关联的分集。
• 全球性网络频道（如 Netflix）的分集不包含在此端点，请用 Web/streaming schedule。
• 英国的国家码是 GB，不是 UK。

3.2.1 通用日程 Schedule

3.2.2 流媒体 / 网络频道日程 Web/streaming schedule

TVmaze 把网络频道分为两类：

• 本地网络频道：只在某一个国家可用。
• 全球网络频道：在多个国家都可用。

country 参数的三种写法决定查询范围：

实测补充：该端点返回的每条分集已自带 _embedded.show（剧集信息），无需额外请求。

3.2.3 全量日程 Full schedule

用途：TVmaze 已知的所有未来分集，不分国家。

注意：与其他端点不同：响应体至少数 MB，且结果缓存 24 小时。适合离线批处理，不适合放进实时接口。

---

3.3 剧集 Shows

3.3.1 剧集主信息 Show main information

取某部剧的全部主信息，支持 embed。

3.3.2 剧集分集列表 Show episode list

该剧的全部分集，按播出顺序返回，每条含完整分集信息。默认不包含特别篇（specials）。

3.3.3 替代分集列表 Show alternate lists

一部剧的替代分集顺序，例如 DVD 发行顺序、首播顺序等。不同列表类型的定义见官方 alternate episode policy。这组端点共三个：

① 列出该剧的所有替代列表

② 取单个替代列表详情

③ 取该替代列表下的分集

实测补充：替代列表对象包含一组布尔标记（dvd_release、verbatim_order、country_premiere、streaming_premiere、broadcast_premiere、language_premiere）用于说明该列表的类型；替代分集通过 _links.episodes 关联到正式分集（可能是一对多）。

3.3.4 按季号 + 集号取分集 Episode by number

根据季号 + 集号取该剧的某一集；返回该分集的完整信息，或 HTTP 404。

3.3.5 按播出日期取分集 Episodes by date

取该剧在指定日期播出的全部分集；返回完整分集信息数组，或 HTTP 404。对日播节目、脱口秀这类不遵循常规季/集编号的节目特别有用。

3.3.6 剧集的季列表 Show seasons

该剧全部季，按季号升序返回，含每季的全部已知信息。

某一季的分集 Season episodes

该季的分集列表。特别篇（specials）始终包含在内，且支持 embed。

3.3.7 剧集主演阵容 Show cast

主要演员列表。每一项是「人物 + 角色」的组合；按重要性排序，重要性由该角色在本剧中的出场总次数决定。

3.3.8 剧集幕后职员 Show crew

主要幕后职员列表。每一项是「人物 + 职类（crew type）」的组合。

3.3.9 剧集别名 Show AKA's

该剧的别名（AKA）列表。country 为 null 的条目表示该剧原产国的别名；否则表示该剧在指定国家使用的别名。

3.3.10 剧集图片列表 Show images

该剧全部可用图片。图片 type 可为 poster、banner、background、typography，或 NULL（历史遗留的未分类图片）。类型定义见官方 main image 与 general image 规范。

所有类型都有 original（原始分辨率）；poster 和 banner 额外提供 medium（缩放后的较小尺寸）。

3.3.11 全库剧集索引 Show index

TVmaze 全库剧集列表，含每部剧的全部主信息，适合用来建立本地缓存。

分页规则：

• 每页最多 250 条；分页基于剧集 ID（例如 page 0 为 ID 0～250 之间的剧）。
• 因删除记录，单页可能少于 250 条；但好处是删除不会导致其他剧集的页码重排。
• 因此可从上次的页码断点续传：若本地缓存最后一个剧集 ID 是 1800，就从 floor(1800/250) = 7 页重新开始，然后逐页 +1，直到收到 HTTP 404（表示已到列表末尾）。
• 注意：与其他端点不同，本端点结果缓存最长 24 小时。

---

3.4 分集 Episodes

3.4.1 分集主信息 Episode main information

取某一集的全部主信息，支持 embed（例如 embed=show 把所属剧集一起返回）。

3.4.2 分集客串演员 Episode guest cast

该集的全部客串演员。

3.4.3 分集客串职员 Episode guest crew

参与该集制作的客串职员。

---

3.5 人物 People

3.5.1 人物主信息 Person main information

取某个人物的全部主信息，支持 embed。

3.5.2 人物主演作品 Person cast credits

该人物的全部剧集级主演记录。一条 cast credit 是「剧集 + 角色」的组合。默认只返回对各剧集与角色的引用（_links）；支持 embed，可把剧集和角色的完整信息一并包含。

3.5.3 人物幕后作品 Person crew credits

该人物的全部剧集级幕后记录，一条为「剧集 + 职类」。默认只返回剧集引用；支持 embed 返回剧集完整信息。

3.5.4 人物客串作品 Person guest cast credits

该人物的全部分集级客串记录，一条为「分集 + 角色」。默认只返回引用；支持 embed 返回分集与角色完整信息。

3.5.5 全库人物索引 Person index

与剧集索引相同，只是对象换成人。

---

3.6 更新 Updates

3.6.1 剧集更新 Show updates

返回 TVmaze 全库剧集及其最后更新时间戳的映射。

重要：更新剧集的直接或间接子资源，也会把该剧标记为已更新。例如新建、删除、修改某一集，或修改某集的图库条目，都会触发该剧的更新时间变化。

可按时间范围过滤，只保留最近更新过的剧集：

实测补充：返回的是 JSON 对象（字典），形如 { "3": 1690000000, "5": 1690000001, ... }，键为剧集 ID 字符串，值为更新时间戳；不是数组。

3.6.2 人物更新 Person updates

与剧集更新类似，但对象换成人。人物被视为「已更新」的情形：自身任一属性变化，或涉及该人物的一条 cast / crew credit 被创建或删除。

---

四、通用机制与使用政策

4.1 嵌入 Embedding

按 HAL 规范，API 资源可以包含指向相关 URL 的链接。这些 URL 可能指向集合（如分集列表）或单个资源（如某一集）。

• 指向单个资源的引用，总会出现在模型的 _links 中，例如剧集的 _links.previousepisode、cast credit 的 _links.character。
• 指向集合的引用不会主动出现在 _links 输出里，但在本文档的端点列表中有说明。
• 两类链接都可以通过 embed 查询参数嵌入到本次响应中。

# 一次请求同时拿到剧集主信息 + 全部分集
https://api.tvmaze.com/shows/1?embed=episodes

# 嵌入该剧「下一集」的详情（仅当确实存在下一集时才有内容）
https://api.tvmaze.com/shows/1?embed=nextepisode

# 数组语法：一次嵌入多个链接
https://api.tvmaze.com/shows/1?embed[]=episodes&embed[]=cast

数组语法中的 [] 在部分场景下需要写成 URL 编码 %5B%5D。嵌入后的内容放在 _embedded 字段中（实测）。

官方文档示例中出现过的 embed 取值（可用性取决于目标资源自身拥有的链接）：

4.2 图片 Images

• 多数资源都有 image 属性，指向该项的主图。剧集、人物、角色为竖版海报格式，分集为横版格式。
• 有图时，image 是一个含 medium（固定缩放尺寸）与 original（上传原始分辨率）两个键的字典；尚无图片时为 NULL。
• 允许直接外链（hotlink）TVmaze 图片 CDN，但出于性能考虑建议自行缓存：Web 应用缓存在服务端，桌面/移动端缓存在客户端。
• 图片可无限期缓存：某个具体图片 URL 的内容永远不会改变；若某条目更换了主图，变的是图片 URL 本身。

4.3 HTTPS

所有端点，以及 API 响应中嵌入的链接（指向其他 API 端点或图片 CDN），默认都是 HTTPS；同时也允许通过未加密的 HTTP 访问。

4.4 缓存 Caching

所有输出由 TVmaze 的 HTTP 负载均衡器缓存 60 分钟。因此网站上的信息更新后，最多可能需要 1 小时才会同步到 API。

个别端点缓存更久，已在对应章节标注：/schedule/full 与 /shows?page=:num 均为 24 小时。

4.5 限流 Rate limiting

• 每个 IP 地址每 10 秒至少允许 20 次调用；超限可能收到 HTTP 429。
• 官方特别说明「至少」：限流发生在后端而非边缘缓存。如果客户端只请求 shows、episodes 这类常见/热门端点（而不是搜索、嵌入这类更「独特」、更难命中缓存的端点），很可能永远碰不到上限。
• 收到 429 时，退避几秒再重试即可获得最佳吞吐；特殊情况下官方可能临时收紧限流，所以即便理论上不会超限，也应优雅处理 429，不要当作永久失败。
• 连接管理：不要让 HTTP 连接无谓地保持空闲。要么每次请求后显式关闭，要么复用连接继续请求，要么使用 HTTP/2 多路复用。保留超过 1 条到 TVmaze 服务器的空闲连接，可能导致 IP 被封禁。
• 虽然不是强制要求，官方强烈建议给客户端设置一个能唯一标识自身应用的 HTTP User Agent，便于在出问题时定位或主动联系你。

4.6 CORS

所有端点都已启用 CORS（跨源资源共享），因此可直接在 Web 应用中调用，无需 JSONP，也无需自己搭 HTTP 代理。

4.7 许可 Licensing

使用 TVmaze API 受 CC BY-SA 许可约束：数据可自由用于任何目的（含商业用途），前提是：

1. 恰当地署名 TVmaze 为数据来源；
2. 遵守 ShareAlike（相同方式共享）条款。

署名要求很容易满足：在应用或网站中链接回 TVmaze 即可，例如直接使用 API 返回的那些 url 字段。

4.8 企业版 API Enterprise API

如果业务需要公共 API 未提供的数据或功能，或需要不同的许可、SLA、支持等级，可联系 TVmaze 销售部门商谈。另有面向 Premium 会员的用户级 API（可查看/管理用户数据），文档独立于本文。

---

五、响应字段速览（补充）

本章为实测补充（2026-11-08 请求线上 API 所得），官方 /api 页面只描述端点、不列字段。字段可能随 TVmaze 数据完善而变化，任一字段都可能为 null，取值请以线上返回为准。

5.1 Show（剧集）— /shows/:id

5.2 Episode（分集）— /episodes/:id

5.3 Person（人物）— /people/:id

id、url、name、country { name, code, timezone }、birthday、deathday、gender、image { medium, original }、updated、_links.self。

5.4 Season（季）— /shows/:id/seasons

id、url、number、name、episodeOrder、premiereDate、endDate、network、webChannel、image、summary、_links.self。

5.5 演员 / 职员条目

self: true 表示演员饰演本人；voice: true 表示配音。credits 端点默认只给 _links 引用，加 embed 后才展开为完整对象。

5.6 其他结构

---

六、典型场景与避坑清单（补充）

6.1 建立本地剧集库 / 每日同步

1. 首次全量：循环 /shows?page=N，从 0 开始逐页拉取（每页 ≤ 250），收到 404 即到末页。
2. 日常增量：调用 /updates/shows?since=day，拿到 { id: timestamp } 映射，只重新拉取变化过的 /shows/:id。
3. 断点续传：记住本地最后一个剧集 ID lastId，从 floor(lastId/250) 页继续。
4. 注意：索引结果缓存最长 24 小时，且全局输出缓存 60 分钟，不要做分钟级的实时性假设。

6.2 把外部数据源对齐到 TVmaze

用 /lookup/shows?thetvdb=:id（或 imdb / tvrage）反查 → 301 的 Location 里就是 /shows/:id。记得允许跟随重定向；查不到是 404。

6.3 做追剧日历

• 传统电视网 + 本地流媒体：/schedule?country=GB&date=2026-11-08
• Netflix 等全球流媒体：/schedule/web?date=...&country=（空字符串）
• 只想一次拿全：/schedule/web?date=...（本地 + 全球），或直接用 /shows/:id?embed=episodes 查单剧。
• 英国要用 GB。/schedule/full 太大，别放进前端实时请求。

6.4 做演员作品页

/people/:id?embed=castcredits 一次拿到人物与其作品引用；若需要剧集详情，用 /people/:id/castcredits?embed=show，避免逐条请求。

6.5 避坑清单

---

七、相关链接

---

本文为第三方中文整理，非 TVmaze 官方文档。API 行为如有变更，请以官方页面与 changelog 为准。