快速开始

按道具 ID 或名称查询道具信息与展示图片。只读、免鉴权、支持跨域，直接 GET 就能用。

1. 搜一个道具，拿到它的 itemid：

curl '/search?q=星梦茶会&limit=3'

2. 响应里每条都带图片地址，image 可以直接放进 <img src>：

{
  "query": "星梦茶会",
  "total": 6,
  "count": 3,
  "items": [
    {
      "itemid": 158961,
      "name": "星梦茶会套装",
      "category": "avatar",       "category_name": "装扮",
      "subcategory": "asm_base",  "subcategory_name": "套装",
      "image": "/img/158961.png",
      "images": ["/img/158961.png"]
    }
  ]
}

3. 已知 ID 就直接取：

curl '/items/158961'

三步就够了。剩下的接口都是围绕这两件事展开的：怎么找到道具、怎么按分类浏览。

几个概念

道具分两层分类

粗分类 category 只有 6 个，对应游戏商城的 Tab；细分类 subcategory 有 200 多个，来自客户端自己的分类表，不是自己编的。

完整的两层对照表随时可查：GET /categories。

车系是另一条线

series 和 subcategory 正交 —— 一个车头既属于「车头」也属于 「雷诺配件」。两个一起传是 AND。

图片

image 是首选的一张，images 是全部（主图、_b/_c 变体、动画帧）。约一半道具有图，没有的 image 是 null， images 是 []。图片由 Nginx 直出，可放心并发拉。

万能查询

一个入口吃三种输入：道具 ID、图片名、道具名。 不用先判断手上这串东西是什么，直接丢进来。

curl '/lookup?q=171055'        # 道具 ID
curl '/lookup?q=171055.png'    # 图片名
curl '/lookup?q=20133_b.png'   # 图片变体，会还原到道具 20133
curl '/lookup?q=甜酷CP-麒麟'     # 道具名

返回体固定这个形状，items 里每条的结构和其他接口完全一样：

{
  "query": "20133_b.png",
  "matched_by": "image",
  "total": 1,
  "items": [ { "itemid": 20133, "name": "双髻鲨", "image": "…/20133.png", … } ]
}

matched_by 告诉你它是按什么命中的，便于判断结果可不可信：

搜索道具

只按名称搜索，中文子串匹配，按相关度排序。

/search?q=雷诺&category=kart            雷诺相关的赛车
/search?q=天使&subcategory=car_new_a    只要 A级赛车
/search?q=天使&limit=5&facets=false     只要结果，不要分类统计

响应在 items 之外还有 total（总命中）、 categories / subcategories（各分类命中数，facets=true 时）。

查单个

查不到返回 404。加 ?full=true 额外返回 restype、 itemselltype、modify_time 和 raw（客户端原始记录， 字段很多，一般用不上）。

curl '/items/158961'
curl '/items/158961?full=true'

批量查

逗号分隔，一次最多 200 个。返回顺序与传入顺序一致，查不到的不占位、 单独列在 missing 里。

curl '/batch?ids=158961,10008,12720'

{"requested":3, "found":2, "missing":[12720], "items":[…]}

展示一批道具时用这个，别循环调单个接口。

分页列表

不带关键词地按条件翻页。

/items?subcategory=car_new_s&size=50          所有 S级赛车
/items?subcategory=car_new_a,car_new_b        A车 + B车
/items?series=other_refititem_renault         雷诺车系全部配件
/items?category=avatar&page=2&size=100        装扮第 2 页

响应带 total 和 pages，直接拿去渲染分页器。

分类表

两层分类树，每层带道具数量。做分类导航就靠它，别把 code 写死在前端。

{"categories":[
  {"code":"kart","name":"赛车","count":3493,
   "subcategories":[
     {"code":"car_new_a","name":"A级赛车","itemtype":1539,"count":729},
     {"code":"car_new_s","name":"S级赛车","itemtype":1543,"count":177}
   ]}
]}

加 ?empty=true 连一条道具都没有的分类也列出来； 加 ?has_image=true 只统计有图的。

车系表

车系配件对照表，配合 /items?series= 用。

枚举表

客户端原始常量的数值 → 名称映射（itemtype、garagetype、 sextype 等）。一般用不上 —— 响应里已经带了 *_name 字段。

数据统计

道具/图片总数、各分类数量、最常见的 itemtype。另有 GET /healthz 供监控探活，返回 {"ok":true,"items":67369}。

ID 名称对照表

全部 135,689 个道具的 itemid + 名字，静态文件直接下载， 不用调接口。适合在本地做 ID 反查、批量校对、离线搜名字。

curl -O '/download/qqspeed-items-idname.csv'

CSV 三列，JSONL 三个字段：

itemid,name,sources
10008,"腾彩气球",ItemList|Client1

{"itemid":10008,"name":"腾彩气球","sources":["ItemList","Client1"]}

响应字段

所有返回道具的接口，单条道具的结构都一样：

错误码

400 / 404 的 detail 是字符串，422 的是数组。两种都要能处理 —— 最省事的写法是只看状态码，需要展示原因时再判断 detail 的类型。

标识你的应用

可选。带上它，你的调用就能被单独统计出来，而不是跟别人混在一起按 IP 猜。

每次请求加一个请求头，值自己起，8～64 个字符，只能用字母、数字和 - _ . :：

curl -H 'X-Client-Id: myapp-prod-01' '/search?q=天使'

不方便加请求头（比如直接在浏览器地址栏、或者小程序里拼 URL）就用查询参数，效果一样：

/search?q=天使&client_id=myapp-prod-01

不带也能正常用，接口行为、返回内容、限流都完全不受影响 —— 这个值只进统计， 不参与鉴权，也不做配额。