开放 API

登录后在「账户」申领 API Key，可自建查询站：输入用户名返回相关信息与曝光结果。查询次数按你共享并核验通过的用户数据计量。

额度规则

默认额度 0；仅「本站库中原先不存在」且核验为真实的用户：1 条 = 1 次查询。
已在 users 库中的 ID/@用户名：导入会被拒，不加额度（防止刷已知数据）。
库外真伪核验顺序：只读桥接 → Bot/Telethon 解析 @用户名并锁定数字 ID → 仅数字 ID 时尝试 Bot getChat。
锁不住数字 ID（软锁定）、编造数据、群/频道：不加额度。
同一贡献者重复导入同一人不再加额度；核验通过后会写入本站镜像，供他人查询。
每次 lookup 成功扣 1 次（无论是否查到曝光）。

接入地址

Base URL：

https://suohen.online/api/v1.php

鉴权（任选其一）：

请求头 Authorization: Bearer sk_sh_...
请求头 X-Api-Key: sk_sh_...
查询参数 api_key=sk_sh_...（不推荐，易泄露）

1. 健康检查 · ping

GET /api/v1.php?action=ping（无需 Key）

curl -s "https://suohen.online/api/v1.php?action=ping"

2. 查询额度 · quota

GET /api/v1.php?action=quota

curl -s "https://suohen.online/api/v1.php?action=quota" \
  -H "Authorization: Bearer sk_sh_你的密钥"

字段	说明
query_credits	累计获得额度
query_used	已消耗次数
remaining	剩余可查次数

3. 查询用户 · lookup

输入 @用户名 / 数字 ID / 关键字，返回相关信息与已曝光记录（可对接重建查询站）。

GET /api/v1.php?action=lookup&q=@username

curl -s "https://suohen.online/api/v1.php?action=lookup&q=@sw11018" \
  -H "Authorization: Bearer sk_sh_你的密钥"

或 POST JSON：

curl -s "https://suohen.online/api/v1.php?action=lookup" \
  -H "Authorization: Bearer sk_sh_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"q":"@sw11018"}'

字段	说明
exposed	是否有已认定曝光
items[]	曝光档案（摘要、别名、时间等）
profiles[]	库内相关身份信息（无曝光时也会返回）
message	如「有相关信息但暂无已曝光记录」
quota	本次扣次后的额度

前端展示建议：有 profiles 先展示身份卡；无 items 时提示无曝光记录。

4. 导入共享用户 · import

批量导入用户数据；仅核验通过的条数增加查询额度。也可在账户页手动粘贴 JSON。

POST /api/v1.php?action=import

curl -s "https://suohen.online/api/v1.php?action=import" \
  -H "Authorization: Bearer sk_sh_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
  "users": [
    {"tg_user_id": "123456789", "username": "alice", "first_name": "Alice"},
    {"chat_id": "987654321", "username": "bob", "first_name": "Bob", "last_name": "Li"}
  ]
}'

字段（每条）	说明
tg_user_id / chat_id / id	Telegram 数字 ID（推荐）
username / tg_username	公开用户名（4–64，字母数字下划线）
first_name / last_name	可选姓名

响应：verified 新用户核验通过数、already_in_db 库中已有数、credits_added 新增额度、rejected（含 code：already_in_db / unverified / soft_only 等）、duplicate_skipped。

单次最多 500 条。

错误码

HTTP	含义
400	参数错误 / 导入失败
401	缺少或无效 API Key
402	查询额度不足
404	未知 action
500	服务器错误

自建站最小示例（伪代码）

async function search(q) {
  const r = await fetch(
    'https://suohen.online/api/v1.php?action=lookup&q=' + encodeURIComponent(q),
    { headers: { Authorization: 'Bearer ' + YOUR_KEY } }
  );
  const data = await r.json();
  if (!data.ok) throw new Error(data.error);
  // data.profiles → 相关信息
  // data.items → 曝光信息
  // !data.exposed → 提示无曝光记录
  return data;
}