GET /v1/games/{uniqueId}/patches

获取 Galgame 补丁

按公开 uniqueId 返回该条目下 Galgame 补丁分类的公开资源元数据。默认只允许 SFW 条目；传入 `allowNsfw=true` 时允许返回 NSFW 条目的补丁。响应不包含真实资源下载地址、提取码、上传者或内部 source 字段。

接口基础信息

接口名称

获取 Galgame 补丁

请求方法

GET

请求路径

/v1/games/{uniqueId}/patches

鉴权

需要有效的 `tgal_live` API token。

请求参数

参数	位置	必填	类型	说明
`Authorization`	Header	条件必填	`Bearer token`	推荐方式。值为 `Bearer <tgal_live API token>`。与 `X-API-Token` 二选一。
`X-API-Token`	Header	条件必填	`string`	备选方式。与 Authorization 二选一；同时传入有效 Bearer header 时优先使用 Authorization。
`uniqueId`	Path	是	`string, 8 alphanumeric chars`	公开 8 位条目 ID，仅允许英文大小写字母与数字。
`allowNsfw`	Query	否	`boolean, default false`	是否允许返回 NSFW 条目的补丁。默认 false，NSFW 条目会按未找到处理；设为 true 时允许返回 SFW 与 NSFW。只接受 true 或 false；其他值返回 BAD_REQUEST。

请求示例

业务接口不要在不可信浏览器环境暴露 token。示例 base 取自 NUXT_PUBLIC_API_BASE_URL，同源相对路径会自动拼接当前域名。

curl

curl "https://developer.touchgal.com/api/v1/games/abcd1234/patches?allowNsfw=true" \
  -H "Authorization: Bearer tgal_live_xxx"

返回状态码与响应示例

200

OK

返回可见条目的 Galgame 补丁列表。条目存在且可见但没有该类型资源时仍返回 200，且 `data.items` 为 []。

application/json

{
  "success": true,
  "data": {
    "items": [
      {
        "name": "中文补丁",
        "description": "公开补丁简介。",
        "categories": ["Patch"],
        "sizes": ["512MB"],
        "publishTime": "2024-05-31T10:00:00Z",
        "deepLink": "https://www.touchgal.ink/abcd1234?tab=resources&resourceId=43&resourceSection=patch"
      }
    ]
  }
}

返回内容解释

success: 固定为 true。
data.items: Galgame 补丁数组；无该类型资源时为空数组。
data.items[].name: 补丁资源名称。
data.items[].description: 补丁资源简介，来自 clean DB 的公开 introduction。
data.items[].categories: 补丁分类数组。
data.items[].sizes: 去重后的补丁大小文本数组。
data.items[].publishTime: 补丁发布时间。
data.items[].deepLink: TouchGal 页面跳转链接，用于打开对应条目的 resources tab 并定位补丁；不是下载链接。

400

Bad request

uniqueId 不是 8 位、包含非英文大小写字母/数字字符，或 allowNsfw 不是 true/false。

application/json

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters"
  }
}

返回内容解释

success: 固定为 false，表示请求失败。
error.code: 稳定错误码，可用于客户端分支处理。
error.message: 面向开发者的错误摘要，不包含内部 SQL、token、DSN 或其他敏感信息。

401

Unauthorized

缺少 API token、token 格式错误、token 已删除，或所属应用/账号不可用。

application/json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API token"
  }
}

返回内容解释

success: 固定为 false，表示请求失败。
error.code: 稳定错误码，可用于客户端分支处理。
error.message: 面向开发者的错误摘要，不包含内部 SQL、token、DSN 或其他敏感信息。

404

Not found

未找到该公开 uniqueId、对应条目已删除/不可公开，或目标是 NSFW 且本次请求未设置 `allowNsfw=true`。条目存在且可见但无 Galgame 补丁不是 404。

application/json

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

返回内容解释

success: 固定为 false，表示请求失败。
error.code: 稳定错误码，可用于客户端分支处理。
error.message: 面向开发者的错误摘要，不包含内部 SQL、token、DSN 或其他敏感信息。

429

Rate limited

触发预认证 IP 限流，或触发 token、账号、应用三维之一的分钟/日限流。通过 token 认证后触发的限流响应会带 X-RateLimit-* 计数；预认证 IP 限流不会带这些响应头。

application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded"
  }
}

返回内容解释

success: 固定为 false，表示请求失败。
error.code: 稳定错误码，可用于客户端分支处理。
error.message: 面向开发者的错误摘要，不包含内部 SQL、token、DSN 或其他敏感信息。
X-RateLimit-Limit-Minute: 通过 token 认证后返回；本次认证上下文下最紧的分钟额度。
X-RateLimit-Remaining-Minute: 通过 token 认证后返回；当前分钟窗口剩余额度。
X-RateLimit-Limit-Day: 通过 token 认证后返回；本次认证上下文下最紧的日额度。
X-RateLimit-Remaining-Day: 通过 token 认证后返回；当前日窗口剩余额度。

500

Internal error

服务端内部错误或限流依赖异常。客户端应记录 request id 并稍后重试，不应把它当作参数错误处理。

application/json

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

返回内容解释

success: 固定为 false，表示请求失败。
error.code: 稳定错误码，可用于客户端分支处理。
error.message: 面向开发者的错误摘要，不包含内部 SQL、token、DSN 或其他敏感信息。