TouchGal API Docs
TouchGal API 文档
稳定、脱敏、可限流的 Galgame 元数据 API。公开业务接口需要 API token；健康检查与就绪检查无需 token。游戏搜索、详情、资源与补丁接口默认只返回 SFW 条目；调用方可通过 `allowNsfw=true` 显式允许 NSFW 条目。
快速开始
注册开发者账号
通过邮箱验证码登录开发者门户；登录态只使用 HttpOnly Cookie。
提交 API 申请
在开发者门户提交账号级应用申请，等待管理员 approved。
创建 API token
审批通过后创建 tgal_live token。明文只在创建响应中返回一次。
调用 /v1 接口
使用 Authorization Bearer 或 X-API-Token 调用业务接口，并处理 400 / 401 / 404 / 429 等状态。
Endpoints
接口目录
健康检查
/v1/health
返回 API 进程是否存活，不访问 PostgreSQL、Redis 或源数据库。适合负载均衡的轻量存活探针。GET就绪检查
/v1/ready
检查 clean PostgreSQL 与 Redis 依赖是否可用，不触碰 TouchGal 主库。适合部署平台的 readiness probe。GETToken 自检
/v1/me
验证当前 token，并返回该 token 所属应用与实际生效的请求额度。不会返回 token 明文或 token hash。GET搜索条目
/v1/games/search
按关键词搜索 clean DB 中未删除的公开 Galgame 条目。默认只返回 SFW；传入 `allowNsfw=true` 时会同时返回 SFW 与 NSFW 条目。搜索结果按相关度排序：标题匹配优先，其次是别名匹配，最后是标签、厂商等其他索引文本。GET条目详情
/v1/games/{uniqueId}
按公开 uniqueId 返回游戏详情、别名、标签、会社与评分聚合。默认只返回 SFW；传入 `allowNsfw=true` 时允许返回 NSFW。响应不包含内部来源 ID、主站用户、评论或资源下载链接。GETGalgame 资源
/v1/games/{uniqueId}/resources
按公开 uniqueId 返回该条目下 Galgame 资源分类的公开资源元数据。默认只允许 SFW 条目；传入 `allowNsfw=true` 时允许返回 NSFW 条目的资源。响应不包含真实资源下载地址、提取码、上传者或内部 source 字段。GETGalgame 补丁
/v1/games/{uniqueId}/patches
按公开 uniqueId 返回该条目下 Galgame 补丁分类的公开资源元数据。默认只允许 SFW 条目；传入 `allowNsfw=true` 时允许返回 NSFW 条目的补丁。响应不包含真实资源下载地址、提取码、上传者或内部 source 字段。鉴权
`/v1/games/*` 与 `/v1/me` 支持 `Authorization: Bearer <api_token>` 或 `X-API-Token`。API token 由开发者门户生成，明文只展示一次；前端页面不要把 token 存入 localStorage 或暴露给不可信浏览器环境。
限流
token 认证接口会按 token、账号、应用三维独立计数。响应头包含 `X-RateLimit-Limit-Minute`、`X-RateLimit-Remaining-Minute`、`X-RateLimit-Limit-Day`、`X-RateLimit-Remaining-Day`。
响应约定
所有 JSON 响应都使用统一 envelope。成功响应为 `success: true`；失败响应为 `success: false` 并返回稳定错误码。
{
"success": true,
"data": {}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request parameters"
}
}