SteamGridDB与IGDB API密钥接入：游戏封面与元数据抓取实践

本地游戏库铺到几百个条目以后最扎眼的往往不是元数据缺失而是封面那一栏——竖版封面拉伸变形、横版横幅糊成一团、独立游戏干脆只剩一个灰底问号。前端刮削器自带的数据源覆盖有限正版商业游戏的图还能凑合模拟器 ROM、独立小作品、老主机移植版基本抓瞎。这时候就该把 SteamGridDB 和 IGDB 这两套图库 API 接进来了前者是社区自发的封面资源站竖版 grid、横版 hero、透明 logo、方形图标一应俱全后者是结构化的游戏数据库年份、类型、平台、简介这些元数据齐全封面图也带多种分辨率。我自己给家里的客厅主机做媒体库那阵子这两家的密钥前后折腾了小半个月踩过的坑不比写的代码少。这篇就把 API 密钥从申请、验证、缓存到实际调用的完整链路拆开讲适合正在做游戏库前端、自建媒体墙、模拟器整合包皮肤或者单纯想批量补齐封面图的朋友参考代码部分只要求会看 Python 和 curl 就行。1. 先分清两个图库各管什么别一上来就申请密钥很多人拿到需求第一反应是两个都申请谁有图用谁结果写出来的逻辑又臭又长还容易在分页和限流上翻车。这两家的定位差异其实非常大先搞清楚边界后面的代码能少写一半。1.1 SteamGridDB专治封面丑、比例错、没图SteamGridDB 的全部价值就在图上它不提供游戏简介、发行日期、类型标签这类元数据。它的资源被分成四类这个分类方式直接决定了你前端的目录结构grids竖版封面最常用的是 600×9002:3也有 512×512、1024×1024 的方形版本以及 460×215、920×430 的横版heroes顶部大横幅1920×620 是标准尺寸4K 屏要 3840×1240logos透明背景的游戏标题字尺寸不固定适合叠在 hero 上面icons方形小图标从 8×8 到 1024×1024 都有它的检索能力也围绕图片设计按游戏 ID 拉图可以按尺寸dimensions、风格styles比如alternate、blurred、no_logo、material、文件类型mimes、是否动图types过滤。这意味着你完全可以写死一套筛选规则让脚本自动挑出600×900、PNG、非动图、非 NSFW的图不用人工一张张点。我实际用下来最省心的策略是优先取 600×900 PNG找不到再退到 512×512最后才用 460×215 裁切。这个优先级不是我拍脑袋定的而是因为绝大多数前端不管是网格布局还是卡片流默认按 2:3 的比例留位塞方图进去会留白塞横图会裁掉两边而裁切是唯一能保证视觉统一的兜底手段。1.2 IGDB元数据是主菜封面是配菜IGDB 的逻辑反过来。它本质上是一个游戏信息数据库字段设计得非常细name、summary、first_release_dateUnix 时间戳、genres、platforms、involved_companies、rating、aggregated_rating还有cover、screenshots、artworks、videos这些媒体字段。封面只是其中一个关联对象拿到的是一张图的 ID 和 URL 模板还得自己拼域名、选尺寸。所以两者在项目里的角色应该这样切维度SteamGridDBIGDB核心产出图片资源本身结构化游戏元数据图片风格社区美化、艺术化官方发行素材、偏原始检索入口游戏名自动补全、游戏 IDApicalypse 查询语言鉴权方式单个长期 API KeyClient ID Secret 换临时令牌适合场景补齐封面、做视觉美化建库、做筛选、做详情页图文覆盖冷门老游戏覆盖好商业作品数据全一句话总结用 IGDB 建索引、定条目用 SteamGridDB 修脸。先把游戏名、年份、平台这些从 IGDB 拉回来建成本地条目再拿条目名去 SteamGridDB 搜图这个顺序比反过来合理得多——因为 SteamGridDB 的搜索结果里经常混进同名的 MOD、合集包和重制版没有年份和平台做交叉校验很容易抓错图。1.3 为什么不用现成的刮削器可能有人会问市面上已经有一堆成熟的媒体库前端自带刮削为什么还要自己调 API我的实际体验是三点一是可控性自带刮削器的匹配算法是黑盒同名游戏匹配错了你没法干预自己写就能加年份差超过 2 年就跳过这种土办法二是批量补图几百个条目一个个手动点太痛苦脚本跑一遍十分钟完事三是自定义前端如果你用的是自己写的网页看板或者魔改过的启动器皮肤压根没有现成插件可用。当然代价是你得自己处理限流、缓存、错误重试这部分后面会详细讲。2. 密钥形态差异一个静态串一个动态令牌这是新手最容易混淆的地方。两个服务都叫API 密钥但机制完全不同一套代码写下来必须用两种封装方式硬套同一个 HTTP 头会直接吃 401。2.1 SteamGridDB 的 API Key 是长期凭据SteamGridDB 发的是一个固定字符串拿到之后所有请求统一塞进请求头Authorization: Bearer 你的KEY这个 Key 不会过期除非你手动在后台吊销重建。好处是简单坏处是一旦泄露就是永久泄露所以绝对不能硬编码进前端 JS 或者提交到公开仓库。我自己是放在环境变量里Docker 部署时用--env-file注入本地开发用.env加.gitignore。还有一点要注意它的 Key 权限是全量的不存在只读或只写的区分。所以如果你要分享代码给朋友务必先吊销自己那把再给人别想着我用完再删——Git 历史里删掉的文件照样能被翻出来。2.2 IGDB 走的是 OAuth2 客户端凭证模式IGDB 的鉴权是标准的两步走先拿Client ID和Client Secret去换access_token再用Client IDaccess_token请求数据接口。这个令牌有明确的有效期官方返回的expires_in通常是五千万秒左右接近 60 天但实际会因为各种原因提前失效所以不能当永久凭据用。请求头的写法是双头并行Client-ID: 你的Client ID Authorization: Bearer access_token这里有个高频错误很多人把Client-ID写成Client-Id或者client-id某些 HTTP 库会做头名大小写归一化某些不会结果就是间歇性 401。我的做法是直接照抄文档里的大小写不做任何美化。2.3 密钥存放的三种位置与取舍存放方式安全性适用场景注意点硬编码进源码极低绝不应该一旦推送到公开仓库等于全公开.env文件中本地开发、单机部署必须加进.gitignore权限设 600系统环境变量 / 容器注入较高服务端部署日志里要过滤掉别打印出完整值密钥管理服务高多机协作个人项目一般用不上我这边的习惯是在项目根目录建一个config.py统一从环境变量读读不到就抛异常退出而不是给个默认空字符串——空字符串会导致请求发出去才报 401排查起来更绕import os def require_env(name: str) - str: value os.environ.get(name, ).strip() if not value: raise RuntimeError(f环境变量 {name} 未配置) return value SGDB_API_KEY require_env(SGDB_API_KEY) IGDB_CLIENT_ID require_env(IGDB_CLIENT_ID) IGDB_CLIENT_SECRET require_env(IGDB_CLIENT_SECRET)3. SteamGridDB API Key 从申请到跑通第一个请求整个流程不长但从注册到第一次成功返回 JSON中间有几个地方会卡住我按实际顺序走一遍。3.1 注册与生成 Key 的操作路径先进官网注册账号登录后在个人偏好设置里找 API 相关的分区点生成新密钥填一个用途描述随便写比如 local library scraper确认后页面会显示一串密钥。这串东西只显示一次页面刷新就再也看不到了所以务必当场复制到密码管理器或者本地文本里。我见过有人刷新页面之后满世界找客服重置的虽然能重建但旧的会立刻失效正在跑的任务全断。生成之后建议立刻做一件事用 curl 打一次最小请求确认可用。别等到代码写完再测那样一旦报错你分不清是密钥问题还是代码问题。3.2 用命令行验证 Key 是否生效最小验证请求用游戏名自动补全接口最方便export SGDB_API_KEY你的密钥 curl -s -H Authorization: Bearer ${SGDB_API_KEY} \ https://www.steamgriddb.com/api/v2/search/autocomplete/hollow \ | head -c 600返回的 JSON 结构大致是{success: true, data: [{id: 12345, name: Hollow Knight, ...}]}。看到success为true并且data里有内容说明 Key 是对的。如果返回{success: false, errors: [Unauthorized]}按这个顺序排查密钥里是不是混进了换行符或空格从网页复制最容易带请求头是不是写成了Authorization: key少了Bearer前缀账号是否处于未激活状态有些站点需要先验证邮箱提示用head -c截断输出是个好习惯。有些游戏名会返回上百条结果终端刷屏之后你还得往回滚浪费时间。3.3 资源接口与筛选参数详解拿到游戏 ID 之后就能按资源类型拉了。以竖版封面为例curl -s -H Authorization: Bearer ${SGDB_API_KEY} \ https://www.steamgriddb.com/api/v2/grids/game/12345?dimensions600x900mimesimage%2Fpngtypesstaticnsfwfalsehumorfalse \ | head -c 800几个参数的实际意义dimensions尺寸过滤多值用逗号。常用的有600x900、512x512、1024x1024、460x215、920x430、342x482、660x930mimes文件类型必须 URL 编码image/png要写成image%2Fpngtypesstatic静态图、animated动图前端不吃动图就直接过滤掉styles风格标签alternate非官方改版、blurred模糊底、no_logo去字标、material材质风、white_logo、black_logonsfw/humor这两个默认是true必须显式传false不然会混进不该出现的图这一点文档里写得不算显眼hero、logo、icon 的接口路径分别换成/heroes/game/{id}、/logos/game/{id}、/icons/game/{id}参数基本一致只是 hero 支持dimensions1920x620这类尺寸过滤logo 和 icon 不支持尺寸过滤因为尺寸本来就不固定。返回体里每张图包含id、url、thumb、width、height、style、author等字段。url是完整可下载地址thumb是缩略图做列表预览时用thumb能省不少流量。3.4 一个容易忽略的坑搜索接口的重名问题search/autocomplete返回的是按名称模糊匹配的游戏列表它不保证第一条就是你要的那个。实测下来搜 ff7 会返回一堆同名不同平台的条目搜中文名直接返回空。所以正确的做法是用 IGDB 拿到的英文原名去搜不要用本地中文名拿到候选列表后用发布日期做二次校验差值超过 2 年的一律丢弃如果候选只有一条直接采信如果没有 IGDB 做交叉校验呢那就退一步把候选列表全拉出来取id最小的那个——这不是什么严谨算法但经验上 ID 越小代表入库越早通常对应原版作品而不是后来的重制版。这是个土办法别当真理用。4. IGDB 的 Client ID / Secret 与令牌获取IGDB 的鉴权链路挂在开发者平台上多一层跳转但只要按顺序做就不会乱。4.1 开发者后台建应用登录开发者平台控制台在应用管理里新建一个应用名称随便填OAuth 重定向 URL 填http://localhost即可因为客户端凭证模式用不到重定向但表单通常是必填项分类选游戏相关。创建完成后会拿到Client ID和Client Secret两个值。Client Secret只显示一次页面离开就看不到但可以重新生成。这个 Secret 的敏感度比 SteamGridDB 的 Key 还要高一级因为它能换出有效令牌令牌又能访问数据接口。建议单独存一份别和 Key 混在一起。注意新注册的应用有一段时间的生效延迟短则几分钟长则几小时。如果刚建完就发请求返回 401先别怀疑代码等一会儿再试。4.2 client_credentials 换 token整个换取过程就是一个 POST 请求参数走查询串export IGDB_CLIENT_ID你的ClientID export IGDB_CLIENT_SECRET你的ClientSecret curl -s -X POST \ https://id.twitch.tv/oauth2/token?client_id${IGDB_CLIENT_ID}client_secret${IGDB_CLIENT_SECRET}grant_typeclient_credentials成功返回{ access_token: xxxxxxxxxxxxxxxxxxxxxxxx, expires_in: 5000000, token_type: bearer }expires_in是秒数五百万秒大概五十多天。但绝对不能等到过期才刷新正确做法是在本地记录一个获取时间 有效期 - 安全余量的过期时间戳安全余量给到 24 小时比较稳。原因很简单令牌快过期时你的批量任务可能跑到一半中途断掉又要从头来。把这段封装成函数import time import requests _TOKEN_CACHE {token: None, expire_at: 0} def get_igdb_token(client_id: str, client_secret: str) - str: now time.time() if _TOKEN_CACHE[token] and now _TOKEN_CACHE[expire_at]: return _TOKEN_CACHE[token] resp requests.post( https://id.twitch.tv/oauth2/token, params{ client_id: client_id, client_secret: client_secret, grant_type: client_credentials, }, timeout15, ) resp.raise_for_status() data resp.json() token data[access_token] expire_in int(data.get(expires_in, 3600)) # 提前一天过期避免任务跑到一半令牌失效 _TOKEN_CACHE[token] token _TOKEN_CACHE[expire_at] now expire_in - 86400 return token细节点评两个timeout必须给不然网络抖动时线程会一直挂着expire_in用get取默认值是因为见过返回体里缺这个字段的异常情况宁可保守按一小时算。4.3 Apicalypse 查询语法入门IGDB 的数据接口用一套自研的查询语言叫 Apicalypse请求体是纯文本不是 JSON。这点很容易踩坑——很多人习惯性发{query: ...}结果返回 400。最基本的游戏查询TOKEN$(curl -s -X POST \ https://id.twitch.tv/oauth2/token?client_id${IGDB_CLIENT_ID}client_secret${IGDB_CLIENT_SECRET}grant_typeclient_credentials \ | python3 -c import sys,json;print(json.load(sys.stdin)[access_token])) curl -s -X POST https://api.igdb.com/v4/games \ -H Client-ID: ${IGDB_CLIENT_ID} \ -H Authorization: Bearer ${TOKEN} \ -H Content-Type: text/plain \ -d fields name,first_release_date,cover.url,platforms.name,genres.name; where name Hollow Knight; limit 1;语法要点拆开说fields后面跟字段名逗号分隔支持嵌套cover.url表示取cover对象里的urlwhere支持、!、、、、多条件用连与或|或search用于模糊匹配比where宽松适合做用户输入不精确的场景limit默认 10最大 500sort排序比如sort first_release_date desc语句结尾必须带分号封面拿到的cover.url长这样//images.igdb.com/igdb/image/upload/t_thumb/co1r7f.jpg。注意三点没有协议头要自己补https:、尺寸是t_thumb可以换、文件名是图 ID。尺寸后缀常用的几个后缀尺寸用途t_thumb90×128列表预览t_cover_small90×128同上t_cover_big264×374卡片展示t_cover_big_2x528×748高分屏卡片t_1080p1920×1080详情页大图替换方式就是字符串替换url.replace(t_thumb, t_cover_big_2x)。这个方法简单粗暴但好用比什么 URL 解析都省事。4.4 限流、错误码与重试策略IGDB 的限流是每秒 4 个请求超了返回 429。批量抓数据时这个限制很容易撞上尤其你还在并发下载图片的情况下。我的处理策略是三层请求层匀速在发请求的地方加time.sleep(0.26)也就是每秒最多 3.8 个留一点余量429 退避捕获到状态码 429 就sleep(1)后重试连续三次还失败就放弃当前条目记日志结果落盘缓存每条查到的元数据立刻写进本地 SQLite 或 JSON 文件下次跑脚本先读缓存只查没查过的第三点最容易被忽略但它其实是效率提升最大的一环。我第一版脚本没有缓存调试过程中重跑了十几次每次都把所有条目重新查一遍白白消耗了大量配额和时间。加上缓存之后迭代速度快了一个数量级。5. 写一个能跑的封面抓取脚本理论讲完来点能直接抄的。这个脚本的目标是读一份本地的游戏名清单先用 IGDB 补全元数据和基准封面再用 SteamGridDB 找美化版封面全部落到本地目录并且支持断点续跑。5.1 目录结构与配置组织project/ ├── .env # 密钥不进版本库 ├── .gitignore ├── config.py # 读环境变量 ├── igdb_client.py # IGDB 封装 ├── sgdb_client.py # SteamGridDB 封装 ├── fetch_covers.py # 主流程 ├── cache.json # 查询缓存 └── output/ ├── grid/ # 竖版封面 ├── hero/ # 横幅 ├── logo/ # 标题字 └── icon/ # 图标.gitignore至少要有这两行.env cache.json output/图片和缓存都不该进仓库一是体积大二是有版权素材在里面公开出去不合适。5.2 两个客户端的封装先写 SteamGridDB 的逻辑简单但要处理搜不到和返回空列表两种情况import requests from typing import Optional, List, Dict class SGDBClient: BASE https://www.steamgriddb.com/api/v2 def __init__(self, api_key: str): self.session requests.Session() self.session.headers.update({Authorization: fBearer {api_key}}) def search_game(self, name: str) - List[Dict]: r self.session.get(f{self.BASE}/search/autocomplete/{name}, timeout15) if r.status_code ! 200: return [] body r.json() return body.get(data) or [] def best_grid(self, game_id: int, size: str 600x900) - Optional[Dict]: params { dimensions: size, mimes: image/png,image/jpeg, types: static, nsfw: false, humor: false, } r self.session.get(f{self.BASE}/grids/game/{game_id}, paramsparams, timeout15) if r.status_code ! 200: return None items (r.json().get(data) or []) if not items: return None # 优先取带 alternate 风格的其次取第一张 for item in items: if alternate in (item.get(style) or ): return item return items[0]mimes这里传的是未编码的原始字符串requests会自动做 URL 编码所以不用手写%2F。这是个容易被教程带偏的地方——有些示例是给 curl 用的直接抄进 Python 反而会双重编码。IGDB 的客户端要处理令牌缓存和查询体拼装class IGDBClient: BASE https://api.igdb.com/v4 def __init__(self, client_id: str, client_secret: str): self.client_id client_id self.client_secret client_secret self.session requests.Session() def _headers(self) - Dict[str, str]: token get_igdb_token(self.client_id, self.client_secret) return { Client-ID: self.client_id, Authorization: fBearer {token}, Content-Type: text/plain, } def find_game(self, name: str) - Optional[Dict]: # 名字里的双引号要转义否则查询语句会断掉 safe_name name.replace(, \\) query ( ffields name,first_release_date,cover.url,platforms.name; f where name {safe_name}; f limit 1; ) r self.session.post(f{self.BASE}/games, headersself._headers(), dataquery.encode(utf-8), timeout15) if r.status_code ! 200: return None data r.json() return data[0] if data else None那个safe_name的转义别省略。游戏名里带引号的不少比如某些带副标题的作品不转义会直接返回 400而且错误信息含糊你得扒文档才能定位。5.3 主流程与断点续跑import json import os import time import requests def load_cache(pathcache.json) - dict: if os.path.exists(path): with open(path, r, encodingutf-8) as f: return json.load(f) return {} def save_cache(cache: dict, pathcache.json): tmp path .tmp with open(tmp, w, encodingutf-8) as f: json.dump(cache, f, ensure_asciiFalse, indent2) os.replace(tmp, path) # 原子替换防写一半断电 def download(url: str, dest: str) - bool: if os.path.exists(dest) and os.path.getsize(dest) 1024: return True try: with requests.get(url, streamTrue, timeout30) as r: r.raise_for_status() with open(dest .part, wb) as f: for chunk in r.iter_content(8192): f.write(chunk) os.replace(dest .part, dest) return True except Exception as e: print(f[下载失败] {url} - {e}) return Falsecache.json的结构设计成{游戏名: {igdb: {...}, sgdb_game_id: 123, files: [...]}}脚本启动时先载入每条处理完立刻写回。这样中途 CtrlC 也不会丢进度。主循环的逻辑就三句话查缓存跳过、查 IGDB 补元数据、查 SteamGridDB 下载图片。写的时候注意在每个网络请求之间加time.sleep别让循环跑太猛。5.4 尺寸适配与前端的命名约定下载下来的文件名一定要有固定规则不然前端读不出来。我用的约定是output/grid/{slug}-600x900.png output/hero/{slug}-1920x620.png output/logo/{slug}.png output/icon/{slug}-512x512.pngslug是游戏名的规范化结果转小写、空格换下划线、去掉:、/、?、*这些路径非法字符长度截断到 60 字符。这里有个坑——纯英文名 slug 化没问题但日文、俄文、中文名直接当文件名在某些文件系统上会出问题稳妥做法是做一层转写或者直接用 IGDB 返回的数字 ID 当文件名前端再用映射表查。我自己的库是 ID 加可读名双轨制文件夹用 ID里面的meta.json存原名前端按 ID 索引人肉查看时看 meta。尺寸方面再强调一次前端布局留的是多少比例你就该下多少比例的图别指望 CSS 的object-fit: cover救场。object-fit只能裁不能补你拿一张 460×215 的横图塞进 2:3 的卡片位裁出来只剩中间一小条人物的头都可能被切掉。这个错误我在第一版里犯过两百多张图全部重下教训很实在。6. 踩坑清单与排查手册下面这些是我和身边几个朋友实际踩过的按报错现象整理成速查表。6.1 高频报错对照表现象最可能的原因处理方式SteamGridDB 返回Unauthorized密钥带了换行或空格strip()之后再用或重新复制SteamGridDB 返回空数组游戏名用了中文或本地译名换英文原名搜或用 IGDB 拿到的nameIGDB 返回 400请求体用了 JSON 而不是纯文本用data传字符串别用jsonIGDB 返回 401令牌过期或Client-ID头大小写不一致重新换令牌头名照抄文档IGDB 返回 429超过每秒 4 次加sleep(0.26)失败退避重试封面下载 403图床有防盗链或 Referer 校验加一个常规的User-Agent头图片下下来是 0 字节请求超时但没抛异常判断文件大小小于 1KB 视为失败重下混进不该出现的图nsfw/humor没显式关掉参数里固定写false6.2 几个文档里不会写的小技巧给图片加后缀校验再落盘。有些返回的url指向 webp你按.png存下去前端解码可能失败。稳妥做法是读Content-Type头来决定扩展名或者干脆统一转成 PNG。我选的是前者省一次转码。批量任务一定要分片。一次跑五百条和一次跑五十条出错概率完全不一样。分片还有一个隐性好处出问题了你只需要重跑一小段不用从头再来。日志里打印密钥要打码。打印SGDB_API_KEY[:6] ****就够了完整值进日志等于泄露。这个习惯不难养成但很多人图省事直接print(key)。缓存文件要原子写。上面代码里的.tmp加os.replace就是这个意思。JSON 写到一半被打断会留下一个损坏的文件下次启动json.load直接抛异常整个脚本起不来。注意图片的版权归属。抓来的封面是社区上传和官方素材自己本地看看没问题如果要做公开的服务或者打包分发得先搞清楚授权。这个不是技术问题但确实是我在项目收尾时才意识到的事。我个人在实际操作中的体会是这套 API 的难点从来不在于怎么调文档写得都还算清楚真正的坑全在边界情况名字匹配不上、图片比例不对、令牌跑到一半过期、网络抖动留下半个文件。这些问题的共同点是第一次遇到时毫无头绪解决过一次之后就再也不会犯。所以我的建议是先用五六条游戏跑通全流程把各种异常都手动制造一遍——拔网线、改错密钥、故意传错参数——观察报错长什么样比闷头写完一整版再调试要省时间得多。另外如果只是给几十个游戏补个图真没必要写脚本手动点可能更快批量上百条的时候前面这些准备工作才真正显出价值。