Skip to content

API Keys Setup ZH

Jump to bottom
hcan359 edited this page Sep 17, 2026 · 5 revisions

API 密钥设置

Tonkatsu Box 使用免费的 API 来获取游戏和电影数据。所有密钥都是免费的，几分钟即可设置好。

IGDB：用于游戏（推荐）

IGDB 由 Twitch（Amazon）提供支持，因此你需要一个 Twitch 开发者账号。

分步操作

  1. 前往 dev.twitch.tv/console 并登录（或创建一个免费的 Twitch 账号）

  2. 点击 Register Your Application

  3. 填写表单：

    • Name：任意名称（例如「my-tonkatsu」）
    • OAuth Redirect URLs：http://localhost
    • Category：Application Integration

  4. 点击 Create

  5. 打开新建的应用 → 复制 Client ID

  6. 点击 New Secret → 复制 Client Secret

  1. 在 Tonkatsu Box 中：进入设置 → API 密钥
  2. 把 Client ID 和 Client Secret 粘贴到 IGDB 部分
  3. 点击验证连接

✅ 完成！现在你可以访问 220 个平台上的 25 万多款游戏。

故障排查

  • 「连接错误」：仔细检查 Client ID 和 Client Secret 是否都复制正确，且没有多余的空格
  • 「未连接」：你的令牌可能已过期，再次点击「验证连接」即可刷新
  • Twitch 要求两步验证：在创建开发者应用之前，你可能需要先在 Twitch 账号上启用两步验证（2FA）

TMDB：用于电影、电视剧和动画（推荐）

  1. 前往 themoviedb.org 并创建一个免费账号
  2. 在你的 TMDB 个人资料中进入 Settings → API
  3. 点击 Request an API Key → 选择 Developer
  4. 填写表单（任何信息都可以，个人使用即可）
  5. 复制 API Key (v3 auth)
  6. 在 Tonkatsu Box 中：设置 → API 密钥 → TMDB 部分 → 粘贴密钥

✅ 完成！现在你可以搜索电影、电视剧和动画。

💡 应用内置了一个 TMDB 密钥，可供基本使用。如果你搜索得比较频繁，建议使用自己的密钥。

内容语言

设置好 TMDB 后，你可以选择电影 / 剧集描述所用的语言：

设置 → 内容语言 → English 或 Русский

这项设置控制来自 TMDB 的标题、描述和题材所用的语言。

TheTVDB：电影与剧集的第二个来源（可选）

在电影和剧集搜索中，TheTVDB 与 TMDB 并列作答；它的剧集还会把自己的季与集带入剧集追踪器。

  1. 前往 thetvdb.com 注册一个免费账号
  2. 打开 thetvdb.com/api-information 申请 v4 API 密钥
  3. 复制密钥
  4. 在 Tonkatsu Box 中：设置 → API 密钥 → TheTVDB API（电影与剧集） → 粘贴密钥 → 测试

测试按钮会执行一次真实登录，因此无效密钥会立即报错。重置 可恢复内置密钥。

说明

  • TheTVDB 不提供用户评分，只有人气值 - 其作品没有评分徽标。
  • 分类和年份筛选在浏览模式下生效。TheTVDB 的搜索接口不接受筛选参数，因此输入查询词后它们不会收窄结果。
  • 未填写密钥时，两个 TheTVDB 标签默认处于关闭状态，而不是让每次请求都失败。
  • 电影现在是多来源的：同一部影片可以分别来自 TMDB 和 TheTVDB，并作为两条独立条目被追踪。升级到 0.42 后，电影封面会重新下载一次，因为封面缓存按来源分了命名空间。

SteamGridDB：用于看板上的游戏美术图（可选）

  1. 前往 steamgriddb.com 并创建一个免费账号
  2. 进入 Preferences → API
  3. 复制你的 API Key
  4. 在 Tonkatsu Box 中：设置 → API 密钥 → SteamGridDB 部分 → 粘贴

✅ 完成！现在你可以浏览高质量的游戏美术图，并将它们添加到看板上。

💡 应用内置了一个 SteamGridDB 密钥。使用自己的密钥是可选的。

ScreenScraper：用于扩展的游戏媒体（可选）

ScreenScraper 提供 IGDB 所没有的额外游戏媒体：原版盒装封面（正面和背面）、3D 盒装渲染图、转盘 / 招牌美术图、标题画面、游戏内截图、同人图和混合渲染图。它覆盖 52 个复古及现代平台（从 NES 到 PS4、Saturn、Dreamcast、街机、掌机等）。

应用内置了开发者凭据，因此该集成开箱即用，但你必须添加一个免费的用户账号才能真正访问 API。

分步操作

  1. 前往 screenscraper.fr 并点击 Inscription（右上角）创建一个免费账号
  2. 确认你的电子邮箱
  3. 在 Tonkatsu Box 中：设置 → API 密钥 → ScreenScraper 部分
  4. 输入你的 ssid（你的 screenscraper.fr 用户名）和 sspassword
  5. 点击 Check Quota 进行验证，你应能看到自己的账号等级、每日配额和每分钟限额

✅ 完成！打开任意受支持平台上的游戏详情页，就会出现一个含额外美术图的媒体画廊。

说明

  • 免费会员每天有 20000 次请求额度，对于正常浏览绰绰有余。结果会在磁盘上保存 30 天，因此再次打开同一款游戏不会产生网络请求。
  • 如果没有找到某款游戏，这个结果也会被保存，这样应用就不会反复重试。
  • 如果你在某款游戏的详情页上什么都看不到，可能是该平台不在受支持列表中，或者游戏名称与任何 ScreenScraper 条目都不匹配。

Comic Vine：用于漫画和图像小说（可选）

Comic Vine 会在书籍搜索标签页中新增一个 Comics 来源：一个庞大的漫画和图像小说系列（卷册）目录，包含出版商、开始年份、期数、封面、创作者和角色。

它没有内置密钥，因此在你添加自己的免费密钥之前，Comics 来源会一直为空。

分步操作

  1. 前往 comicvine.gamespot.com 并创建一个免费账号（右上角 Sign Up）。Comic Vine 属于 GameSpot 网络，因此现有的 GameSpot/Fandom 登录也可以使用
  2. 登录状态下，打开 API 页面：comicvine.gamespot.com/api
  3. 你的个人 API key 显示在该页面顶部，复制它
  1. 在 Tonkatsu Box 中：设置 → API 密钥 → ComicVine 部分 → 粘贴密钥
  2. 点击 Test 进行验证，你应能看到「ComicVine API key is valid」

✅ 完成！打开搜索 → 书籍，Comics 来源现在会返回结果。

说明

  • 免费密钥的速率限制为每小时 200 次请求。正常浏览远低于这个上限。
  • Comic Vine 数据仅供非商业用途。
  • 漫画出现在书籍搜索标签页内，与 OpenLibrary 和 Fantlab 并列，而不是作为单独的标签页。

Hardcover：用于书籍（可选）

Hardcover 会在书籍搜索标签页中新增一个书籍来源，并让你把 Hardcover 书库导入到一个收藏中。它需要一个免费的个人访问密钥。

分步操作

  1. 前往 hardcover.app 并登录（或创建一个免费账号）
  2. 打开你的账号设置
  3. 复制你的个人访问密钥
  4. 在 Tonkatsu Box 中：设置 → API 密钥 → Hardcover 部分 → 粘贴密钥
  5. 点击 Test 进行验证，你应能看到「Hardcover API token is valid」

✅ 完成！打开搜索 → 书籍，Hardcover 来源现在会返回结果。你也可以从设置 → 导入 → Hardcover 导入一个书库。

说明

  • 该访问密钥有效期为一年，每年续期一次，因此你每年需要更换一次。
  • 关于书库导入和版本选择器的工作方式，参见 从 Hardcover 导入。

Podcast Index：用于播客（可选）

Podcast Index 是「音频」标签页背后的播客目录：播客搜索、趋势榜，以及每个播客保存时附带的剧集源。发行版内置了一对密钥，播客开箱即用；自己的一对可以把用量分开。

分步操作

  1. 打开 api.podcastindex.org 并注册
  2. 从账户页复制 API key 和 API secret
  3. 在 Tonkatsu Box 中：设置 → API 密钥 → Podcast Index API → 两个都粘贴进去
  4. 点击 测试 验证，应当看到「Podcast Index 密钥有效」

首次启动的欢迎向导也会询问同一对密钥。

注意

  • Podcast Index 用当前时间为每个请求签名，系统时钟偏差几分钟就会被拒绝。先查时钟，再查密钥。
  • 这对密钥会随设置导出和完整备份一起走。
  • 在自托管的 Web 版上由服务器签名，密文不会进入浏览器。

无需密钥

以下来源无需任何 API 密钥即可使用：

来源 提供的内容
VNDB 视觉小说：搜索、按标签浏览、评分
AniList 动画和漫画：搜索、按题材 / 格式浏览、进度
Kitsu 动画和漫画：搜索、浏览，以及供追踪器使用的逐集数据
MangaBaka 漫画、韩漫、条漫、轻小说：搜索和浏览
MangaDex 漫画：搜索、浏览、本地化标题、章节数
TVmaze 电视剧：按标题搜索、分季、分集、发行日历
OpenLibrary 书籍：按书名或作者搜索、封面、描述
Fantlab 书籍：搜索、各版本各自的封面、相似作品
MusicBrainz 音乐：专辑、艺人、版本与曲目表，封面来自 Cover Art Archive
预制收藏 含完整库的 .xcollx 文件，完全离线

Steam、RetroAchievements 和 Simkl 导入器也需要密钥或登录，但那要在它们各自的导入界面上完成，而不是在这里。参见 从 Steam 导入、从 RetroAchievements 导入 和 从 Simkl 导入。

小结

来源 用途 是否需要密钥？ 设置耗时
IGDB 游戏（25 万多个条目） 是（免费 Twitch 令牌） 约 2 分钟
TMDB 电影、电视剧、动画 是（免费）或使用内置密钥 约 3 分钟
TheTVDB 电影、剧集（第二来源，自带分集） 免费 v4 密钥或使用内置密钥 约 2 分钟
SteamGridDB 看板用的游戏美术图 可选（有内置密钥） 约 1 分钟
ScreenScraper 额外的游戏媒体（52 个平台） 在 screenscraper.fr 上注册免费账号 约 2 分钟
Comic Vine 漫画和图像小说 免费密钥（无内置） 约 2 分钟
Hardcover 书籍（搜索 + 书库导入） 免费访问密钥（无内置） 约 2 分钟
Podcast Index 播客（搜索 + 剧集源） 免费密钥/密文对或用内置 约 2 分钟
VNDB 视觉小说 否 -
AniList / Kitsu 动画、漫画 否 -
MangaBaka / MangaDex 漫画 否 -
TVmaze 电视剧 否 -
OpenLibrary / Fantlab 书籍 否 -
MusicBrainz 音乐专辑 否 -
Simkl 导入电影、电视剧和动画 否，在导入界面用代码登录 约 1 分钟

🏠 Home

🇬🇧 English

🇷🇺 Русский

🇨🇳 中文

💬 Discord

Clone this wiki locally