API 使用文档

1. 接口地址

方法	路径	说明
POST	/v1/xheaders/sign	生成七头签名
GET	/v1/xheaders/health	服务健康状态
GET	/v1/xheaders/self-test	自检（SM3/selector/codeword）

2. 鉴权方式

在控制台注册后获得 qs_ 开头的 API Key，调用签名接口时放入请求头：

Authorization: Bearer qs_你的Key

3. 请求参数

字段	类型	必填	说明
url	string	是	被签名的完整 URL（含 query）
body_b64	string	是	最终 HTTP Body 的 Base64（可为空串）
instance	string	否	设备实例名，留空用服务端默认设备上下文
options	object	否	确定性复现参数（调试用）

4. 请求示例（curl）

curl -X POST https://<host>/v1/xheaders/sign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer qs_你的Key" \
  -d '{
    "url": "https://api.qishui.com/luna/track_v2?aid=8478&_rticket=1784311334346",
    "body_b64": "e30="
  }'

5. 请求示例（Node.js）

// 零依赖：仅用内置 https/fetch（Node 18+）
const resp = await fetch('https://<host>/v1/xheaders/sign', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer qs_你的Key',
  },
  body: JSON.stringify({
    url: 'https://api.qishui.com/luna/track_v2?aid=8478',
    body_b64: Buffer.from(JSON.stringify({x:1})).toString('base64'),
  }),
});
const data = await resp.json();
console.log(data.headers); // X-Khronos / X-SS-STUB / X-Argus / ...

6. 响应结构

{
  "headers": {
    "X-Khronos": "1784311334",
    "X-SS-STUB": "FB72D7B20B5E5BD41547DB9476A8E3D1",
    "X-Argus": "Jm5aag==",
    "X-Gorgon": "8404...",
    "X-Helios": "...",
    "X-Ladon": "...",
    "X-Medusa": "..."
  },
  "diagnostics": { "selector": 3, "profile": "10fde8" }
}

7. 错误码

HTTP	code	说明
401	unauthorized	Key 无效或缺失
403	account_disabled	账号已被管理员禁用
429	rate_limited	QPS 超限（令牌桶限速）
429	daily_quota_exceeded	每日免费额度用尽，次日 00:00 重置
400	invalid_request	请求体非法（缺 url / body_b64）
404	unknown_instance	指定 instance 不存在

8. 配额与限速

每位用户有「每日免费调用次数」配额（默认 1000，管理员可调，每日 00:00 重置）与 「QPS」限速（每分钟请求上限，令牌桶平滑限流）。超限均返回 429， 可在控制台「今日调用情况」查看用量与剩余。