API REFERENCE
直接查询，也可以接入应用。
目录查询使用已保存的本地记录；表情预览首次打开时按需读取并缓存，不会启动整轮扫描。列表统一返回 total 和 data，不附带扫描状态或调试信息。
查询接口
| 方法与路径 | 用途 |
|---|---|
GET /api/v1/packs | 浏览、筛选表情包 |
GET /api/v1/packs/{id}/stickers | 表情预览列表（按需读取并缓存） |
GET /api/v1/packs/{id} | 查询单个已收录的表情包 |
GET /api/v1/users/{user_id}/packs | 查询作者的全部表情包 |
GET /api/v1/packs?all=true | 全部记录，按 ID 升序，单行 JSON |
GET /api/v1/status | 独立查询扫描与索引状态 |
筛选参数
| 参数 | 含义 |
|---|---|
name | 名称包含匹配，1–128 个字符；支持 Unicode 归一化，忽略英文字母大小写 |
author_name | 作者昵称包含匹配，支持组合筛选 |
author_id | 精确匹配作者云湖 ID，以字符串传入 |
id | 精确匹配表情包 ID |
sort | id_asc（默认）、id_desc、created_asc、created_desc |
limit / offset | 每页条数（1–500，默认 100）/ 跳过条数（默认 0） |
all=true | 返回全部匹配记录，不与 limit、offset 混用 |
多个筛选条件同时满足才会返回。指定作者且未传分页参数时，默认返回该作者的全部匹配记录。列表中的 total 始终是匹配总数；如有下一页，响应头 Link 会提供链接。
调用示例
GET /api/v1/packs?name=神秘表情包
GET /api/v1/packs?author_id=100002
GET /api/v1/packs?author_id=100002&name=神秘
GET /api/v1/packs?id=2681
GET /api/v1/packs?limit=50&offset=50
GET /api/v1/packs?all=true
GET /api/v1/packs/2681中文及特殊字符请进行 URL 编码，或使用 URLSearchParams 构造参数。
返回格式
{"total":1,"data":[{"id":2681,"name":"444","author":{"name":"那狗吧","user_id":"8516939"},"sticker_count":0,"created_at":"2026-08-28 09:53:27+08:00","created_unix":1787882007}]}上面是格式示例。单包详情返回 {"data": {...}}；没有匹配项时列表返回 {"total": 0, "data": []}。错误使用对应 HTTP 状态码及 {"error": {"code": "…", "message": "…"}}，不包含调试状态。
AI 对话
目录右上角打开 AI 查找助手，可选择模型，用自然语言描述表情包或作者。模型整理条件后，系统查询本地索引并显示真实结果卡片；点击“查看搜索结果”返回目录。模型由管理员在后台配置。
GET /api/v1/ai/models 获取可用模型，POST /api/v1/ai/chat 接收 model、messages 和可选 mode（sticker 表情包模式，daily 日常对话，默认 sticker）。Token 优先采用服务商统计，缺失部分本地估算并标注来源。AI 对话仅允许本站页面的同源请求。生成时可提交 stream:true 接收 SSE；POST /api/v1/ai/cancel 携带原 request_id 可停止对应生成。
已有调用继续可用
旧的 /api/find、/api/find/user_id=…、/api/find/name_find/str=… 仍保留，q 和 user_id 参数也继续兼容。新应用推荐使用上方标准路径与参数。