GET /v1/games/search

搜索游戏条目

按关键词搜索 clean DB 中未删除的公开 Galgame 条目。默认只返回 SFW；传入 `allowNsfw=true` 时会同时返回 SFW 与 NSFW 条目。搜索结果按相关度排序：标题匹配优先，其次是别名匹配，最后是标签、厂商等其他索引文本。

接口基础信息

接口名称

搜索游戏条目

请求方法

GET

请求路径

/v1/games/search

鉴权

需要有效的 `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。
`keyword`	Query	条件必填	`string, 3-100 Unicode chars`	搜索关键词。`keyword` 与 `q` 二选一；优先读取 `keyword`。空白字符串会按无效参数处理。
`q`	Query	条件必填	`string, 3-100 Unicode chars`	`keyword` 的短别名。仅当 `keyword` 为空字符串时使用。
`page`	Query	否	`integer, 1-100`	页码。默认 1；小于 1 或非整数按 1 处理；超过 100 返回 BAD_REQUEST。
`limit`	Query	否	`integer, 1-50`	每页数量。默认 20；小于 1 或非整数按 20 处理；超过 50 会按 50 裁剪。
`allowNsfw`	Query	否	`boolean, default false`	是否允许返回 NSFW 条目。默认 false，仅返回 SFW；设为 true 时返回 SFW 与 NSFW。只接受 true 或 false；其他值返回 BAD_REQUEST。

请求示例

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

curl

curl "https://developer.touchgal.com/api/v1/games/search?keyword=summer&page=1&limit=10&allowNsfw=true" \
  -H "Authorization: Bearer tgal_live_xxx"

返回状态码与响应示例

200

OK

返回匹配条目列表与分页信息。默认结果只包含 SFW；显式 `allowNsfw=true` 时包含 SFW 与 NSFW。结果按标题匹配、别名匹配、其他索引文本匹配分档排序，同档按相关度排序，并用名称与 uniqueId 保持稳定顺序。搜索列表只包含名称与公开 uniqueId，详情请继续调用条目详情接口。

application/json

{
  "success": true,
  "data": {
    "items": [
      {
        "name": "Summer Pockets",
        "uniqueId": "abcd1234"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "hasMore": false
    }
  }
}

返回内容解释

success: 固定为 true。
data.items[].name: 公开条目名称。
data.items[].uniqueId: 8 位公开条目 ID，可用于详情接口。
data.pagination.page: 当前页码。
data.pagination.limit: 实际生效的每页数量。
data.pagination.total: 当前关键词下可见结果总数。
data.pagination.hasMore: 是否存在下一页。

400

Bad request

关键词缺失、长度不在 3-100 字符、不是有效 UTF-8、page 超过 100，或 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 或其他敏感信息。

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