开发者接入 | StickerHub

01 / 快速开始

快速开始

StickerHub API 为每个已批准的集成签发一把仅供服务端保存的 API Key，并从当前站点的 /api/v1 路径提供公开目录数据。

取得 API Key

从服务管理员处取得调用方密钥。它与 Turso 数据库 Token 完全分离。

发送请求头

在每次请求中发送 X-API-Key。不要把密钥写进公开前端代码。

继续游标

列表响应返回 nextCursor。下一次请求应原样传回，不要解析或展示它。

每个集成使用独立凭据

API Key 由 StickerHub 运营方为已批准的具体集成创建，具有独立的限流、过期和撤销状态。当前不提供匿名自助注册；请申请访问权限，并通过安全渠道接收只展示一次的 Key。

第一个请求

先调用经过认证的健康检查，确认凭据和目录连接都可用。

Shell

curl https://stickerhub.lius.me/api/v1/health \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

02 / 身份验证

身份验证

全部五个端点都需要 API 密钥。密钥缺失或无效时返回 401；请求过多时返回 429。健康检查端点同样需要验证，因此它可以同时确认服务可用性和客户端凭据。

请把密钥保留在服务器端。

在 X-API-Key 请求头中发送签发的 API 密钥。不要把它放进公开浏览器代码，也不要提交到代码仓库。

03 / 分页与错误

游标分页

集合端点返回 data 数组和可为空的 nextCursor。下一次请求应原样传回该游标。默认每页 24 条，允许范围为 1 至 50。游标是不透明值，客户端不应解析它，也不应把它作为面向用户的页码显示。

常见状态码

HTTP	常见状态码
400	请求参数不合法
401	API Key 缺失或无效
404	资源不存在
429	超过请求频率限制
500	服务无法完成请求

JavaScript 示例

所有错误都使用同一个安全结构：error.code 供程序判断，error.message 供用户阅读。服务器异常不会直接暴露。

JavaScript

const response = await fetch('/api/v1/albums?q=cat&limit=24', {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.STICKERHUB_API_KEY,
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(error.code + ': ' + error.message)
}

const { data, nextCursor } = await response.json()

04 / 资源与边界

资源地图

GET/api/v1/health

健康检查

验证 API Key 和服务连接。

GET/api/v1/albums

表情包资源

搜索、分页并读取公开的表情包元数据。

GET/api/v1/members/{md5}

贴纸资源

列出或按 MD5 读取安全的贴纸元数据。

公开数据边界

API 永不返回 aes_key、encrypt_url、raw_json、数据库凭据或来源追踪字段。表情包名称、作者和说明保持目录原文。