OpenSubtitles 国内使用指南
更新于 2026 年 8 月 31 日 · 注册、配额、中转与错误码
一句话：OpenSubtitles 是全球最大的字幕库，国内直连不通、要走中转。真正会卡住人的是它的两个错误码——403 的字面意思是「Api-Key 无效」，但十有八九是 User-Agent 的问题，照字面去换 key 纯属白折腾；406 的正常含义是「今日配额用完」，可少了 Accept 请求头也回 406，两件事撞在同一个码上。另外中转模式下有两件事必须和直连反着做，否则就是典型的「搜得到、下不来」。
它值不值得配
先说清楚定位，免得配了半天发现用不上。只看中文片子的话，射手网(伪) 一家就够了——国内直连，填一个 token 就能用，没有下面这些坑。OpenSubtitles 值得配的是这几种场景：
- 外语片、老片、纪录片：中文站点覆盖有限，这里基本都有。
- 冷门剧集：它能按 IMDb id + 季集号做精确检索，而不是拿一串文件名去碰运气。追美剧英剧到第三第四季，中文站点常常就断了。
- 非中英文的语种：日语、韩语、法语、西班牙语等。
两家在应用里是并搜合并成一张列表的关系，不是主备——配上第二家不会顶掉第一家，只是列表里多出一批候选。这个设计的取舍讲在 外挂字幕自动下载指南里。
第一步：注册与 API Key
- 到
opensubtitles.com注册一个账号（注意是.com，历史上还有一个.org的老站，两边是不同的体系）。 - 在开发者 / Consumers 页面创建一个 consumer，拿到 API Key。免费。
- 回到应用：设置 → 字幕 → 在线字幕 · OpenSubtitles，填入 API Key。
- 再填中转地址（下一节讲）。
- 用户名 / 密码选填：填了每日下载配额更高，不填也能搜。
顺序建议是先把 API Key 和中转配好，能搜出结果之后再决定要不要填账号——配额问题只有在真的下多了才会遇到。
第二步：中转（国内的必选项）
它的 API 域名在国内直连不通，所以设置里有一栏「中转地址」。中转就是一个你自己部署的、把请求原样转发到 OpenSubtitles 的小服务。填上之后，应用的所有请求都从这里走。
这一栏和 TMDB 刮削那边的中转是同一类东西，如果你已经为刮削搭过一个（见电影刮削完全指南），可以复用同一个服务。
中转模式下有两件事必须反着做
这是这篇最值钱的一段，因为它的症状特别有迷惑性：搜索一切正常、结果列表满满当当，一点下载就失败。原因是「让搜索通」和「让下载通」是两件事，中转只办妥前一件的话，最后一步照样连不上。
第一件：登录返回的 base_url，直连时必须认，中转模式下必须丢掉。
OpenSubtitles 的登录接口会在响应里返回一个 base_url，告诉客户端「你之后的请求发到这个地址」。VIP 账号会被指到 vip-api.opensubtitles.com 这样的专属域名，继续打默认域会被拒绝——所以直连的时候这个字段是必须认的，host 得跟着 token 一起存下来。
但走中转时，你的中转服务只反代了 api.opensubtitles.com 这一个域。这时候如果照样去认服务端下发的 base_url，客户端就会绕过你的中转、直接去打那个新域名——而那个域名在国内同样不通。配了中转反而失效，且失效的时机是「登录成功之后」，所以看起来像是登录搞坏了什么东西。正确做法是中转模式下把这个字段丢掉，一切照中转地址走。
第二件：下载直链也要经中转。
下载字幕是两步：先调 /download 接口换一个一次性的下载链接，再去拉那个链接。这两步的域名是不一样的——接口在 api 域，而返回的 link 指向 OpenSubtitles 的下载域，是另一台服务器。中转只反代了 api 域的话，前一步通、后一步不通，症状就是「搜得到、能拿到下载地址、就是下不来」。所以取回的下载直链本身也要改写成经中转的地址。
如果你在自建中转，对应地服务端要放行三件事：放行 POST（登录和下载都是 POST，只做刮削中转的话通常只收 GET）、透传 Authorization 头、以及给下载直链留一条转发路径，并且那条路径的目标 host 要走白名单——不加限制的话你就搭了一个公开的开放代理。
403 说「Api-Key 无效」，但通常不是 key 的问题
这是最浪费时间的一个坑，因为报错信息在主动误导你。
请求被拒时服务端返回 403，附带的文字大意是「Api-Key 无效」。任何人看到这句话的第一反应都是去后台重新生成一把 key——然后换上，还是 403；怀疑是账号问题，重注册一个，还是 403。
真实原因常常是 User-Agent。这套 API 要求每个请求必须带一个具体的 User-Agent——标明是哪个应用、哪个版本。缺这个头一律 403；用 HTTP 库的默认 UA（那种 okhttp/4.x、python-requests/2.x）同样一律 403。而它回给你的错误文字，说的却是 key 的事。
所以排查顺序应该反过来：先确认 UA 带了、且不是默认值，再去怀疑 key。这一条对自己写脚本调它的人尤其重要——网上大量示例代码只贴了 Api-Key 头，照抄必踩。
406 同时代表两件事
另一个撞码的坑，方向和上面相反：这次不是报错文字骗人，而是两个完全不同的问题共用同一个状态码。
在这套 API 里，406 的正常含义是「今日下载配额用完了」。这是个设计上的选择，别的 API 一般用 429。但同时，调 /download 时如果没带 Accept 请求头，也会回 406。
于是你会看到这种情况：账号明明一次都没下过，提示却说配额用完；或者刚换了个新账号，第一次下载就说超额。两者的区分办法很直接：
| 情况 | 特征 | 处理 |
|---|---|---|
| 真的配额用完 | 今天成功下过若干条，之后开始 406；换个时段恢复 | 等重置，或登录账号提高上限 |
缺 Accept 头 | 一条都没成功下过就 406；换账号、换 key 都一样 | 补上请求头 |
判据是「有没有成功过」。一次都没成功而立刻 406 的，几乎可以断定是请求头问题，不是额度问题。
还有三条会咬人的规矩
- JWT 只有 24 小时，而且没有 refresh token。登录拿到的令牌一天就过期，也没有续期机制，只能拿账号密码重新登一次。所以账号密码必须存下来（应用这边交给鸿蒙的系统级密钥库保管，不落明文），过期时静默重登，用户不会看到「请重新登录」这种打断。自己写客户端的话，别只存 token 不存凭据。
- 查询参数要按字母序排。包括多值参数内部也要排。顺序不对时服务端返回 301 重定向——跟不跟随、跟随后请求方法和请求体还在不在，完全看你的 HTTP 客户端实现，所以症状很飘：有的库自动跟随、看起来一切正常，有的库直接把 301 当失败报出来。
- 中文要同时问
zh-CN和zh-TW。这家把简体和繁体当成两种独立的语言收录，只问zh-CN会漏掉大半繁体资源。这一条影响的不只是它一家，详见 简体繁体字幕都想搜到。
常见问题
不填用户名密码能用吗？
能搜、也能下，只是每日下载配额低一些。先不填用起来，遇到配额不够再补。
配额是怎么算的？
按下载次数算，不是按搜索次数。搜索不消耗配额，所以随便搜；真正扣数的是点下去那一下。额度按日重置，登录账号后上限更高。
搜出来一条中文都没有，是不是配错了？
不一定。OpenSubtitles 的中文资源本来就不如英语丰富，冷门片子上一条中文都没有是正常的。这正是要同时配射手网(伪) 的原因——两家并搜，中文那半边由它兜住。
能不能不搭中转？
如果你的网络环境能直连它的 API，可以不填中转，直接用 API Key。中转是为直连不通的情况准备的。另外提醒一句：直连时前面说的 base_url 要认，中转时要丢，两种模式的行为是相反的。
下好的字幕不显示怎么办？
先看文件有没有正确的扩展名——播放器按扩展名挑解析器，没后缀的文件会被静默跳过，不报错。这一类症状的完整分诊见 字幕加载不出来的六种原因。
为什么我的排错日志里看不到这些细节？
因为多数客户端会把 HTTP 层的失败折叠成一句「下载失败」。真要定位，最有效的办法是盯住状态码本身：403 先查 UA，406 先查是不是一次都没成功过，301 查参数排序。把这三条记住，这套 API 就没什么神秘的了。
相关阅读：外挂字幕自动下载指南、简体繁体字幕都想搜到、字幕加载不出来的六种原因。配置上还有问题的话，带上状态码发到支持页上的邮箱。