GET /v1/games/{uniqueId}

获取游戏条目详情

按公开 uniqueId 返回游戏详情、别名、标签、会社与评分聚合。默认只返回 SFW；传入 `allowNsfw=true` 时允许返回 NSFW。响应不包含内部来源 ID、主站用户、评论或资源下载链接。

接口基础信息

接口名称

获取游戏条目详情

请求方法

GET

请求路径

/v1/games/{uniqueId}

鉴权

需要有效的 `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?allowNsfw=true" \
  -H "Authorization: Bearer tgal_live_xxx"

返回状态码与响应示例

200

OK

返回单个公开条目的完整脱敏元数据。

application/json

{
  "success": true,
  "data": {
    "uniqueId": "abcd1234",
    "name": "Summer Pockets",
    "aliases": ["サマーポケッツ"],
    "introduction": "公开简介文本。",
    "bannerUrl": "https://example.com/banner.webp",
    "type": ["ADV"],
    "platform": ["PC"],
    "language": ["ja", "zh-Hans"],
    "tags": ["恋爱", "夏日"],
    "publishTime": "2024-01-20T12:00:00Z",
    "releaseDate": "2018-06-29",
    "updatedAt": "2024-06-01T08:30:00Z",
    "resourceUpdateTime": "2024-05-30T10:00:00Z",
    "companies": [
      {
        "name": "Key",
        "aliases": ["VisualArt's Key"]
      }
    ],
    "rating": {
      "average": 8.7,
      "count": 128,
      "recommend": {
        "strongNo": 1,
        "no": 2,
        "neutral": 8,
        "yes": 42,
        "strongYes": 75
      }
    },
    "touchgalUrl": "https://www.touchgal.ink/abcd1234"
  }
}

返回内容解释

success: 固定为 true。
data.uniqueId: 公开 8 位条目 ID。
data.name: 条目主名称。
data.aliases: 公开别名列表，已去重。
data.introduction: 公开简介文本。
data.bannerUrl: 公开封面/横幅图片 URL。
data.type / platform / language: 条目类型、平台和语言数组。
data.tags: 公开标签名称数组。
data.publishTime: 条目公开发布时间。
data.releaseDate: 游戏发售日期文本。
data.updatedAt: 条目公开元数据更新时间。
data.resourceUpdateTime: 资源元数据更新时间；不包含资源下载链接。
data.companies[].name: 会社名称。
data.companies[].aliases: 会社别名列表。
data.rating.average: 公开评分均值。
data.rating.count: 参与评分人数。
data.rating.recommend: 推荐度直方图：strongNo / no / neutral / yes / strongYes。
data.touchgalUrl: TouchGal 公开条目页面 URL，由 `TOUCHGAL_SITE_URL` 追加 `/{uniqueId}` 生成。

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`。

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 或其他敏感信息。