Technical Guide

从一次 API 调用 到独立 验签

按顺序完成 Request ID 提取、在线查询、证据下载和离线验签。真实日志同步可能需要几分钟。

真实核查不会瞬间完成系统同步真实日志、核对路由、冻结证据并验证检查点，繁忙或重试时可能需要多等几分钟。
00

完成后可以核对的内容

Q-API 记录了指定 Request ID
New API 记录了 OAuth 渠道选择
请求模型与实际转发模型
输入、缓存输入和输出 Token 计量
Ed25519 签名与载荷哈希一致
证据记录进入链式 Merkle 检查点
01

发送最小检测请求

使用较短提示词即可。加上 -i 保留响应头。

>_bash 
1 curl -i https://aiapi.qhunliv13.online/v1/chat/completions \
2   -H "Authorization: Bearer sk-您的API密钥" \
3   -H "Content-Type: application/json" \
4   -d '{
5     "model": "gpt-5.6-sol",
6     "messages": [{"role": "user", "content": "Reply with OK only."}],
7     "max_tokens": 8
8   }'

保存响应头中的 X-QAPI-Request-ID。响应还会给出 X-QAPI-Trace-URL，可直接打开对应查询页。

02

在线查询请求证据

  1. 打开 请求可信验证。
  2. 粘贴完整 Request ID，然后点击「查询」。
  3. 等待系统同步真实日志并生成证据；繁忙时可能需要几分钟。
  4. 核对请求模型、实际转发模型、OAuth 渠道槽位、Token 数和时间。
  5. 点击「本地一键验签」，浏览器会在本机验证签名和哈希。
03

下载并阅读证据包

在查询结果中点击「下载证据包」，得到 qapi-evidence-REQUEST_ID.json。

字段用途核对重点
record冻结后的脱敏请求记录Request ID、模型、渠道、Token
record_attestationQ-API Ed25519 签名载荷 SHA-256 与签名
merkle_proof检查点包含证明leaf、root 和记录哈希
checkpoint链式检查点当前 root 与 previous root
verified_scope本次已验证范围逐项与页面结果对照
04

命令行离线验签

在项目目录执行；验证过程只读取本地 JSON。

>_bash 
1 python -m aiapi.verify_evidence qapi-evidence-REQUEST_ID.json

成功时会依次显示：

OKverifier output
1 [PASS] Q-API record signature
2 [PASS] Merkle inclusion proof
3 [PASS] Checkpoint signature and root
4 
5 Evidence level: L2
6 Verified scope: signed record, routing evidence, and checkpoint integrity.
05

手动复算载荷哈希

需要独立复核时，按 JSON 键名排序并使用紧凑分隔符序列化，然后计算 SHA-256。

PYverify-hash.py 
1 import hashlib, json
2 
3 bundle = json.load(open("qapi-evidence-REQUEST_ID.json", encoding="utf-8"))
4 payload = json.dumps(
5     bundle["record"],
6     ensure_ascii=False,
7     sort_keys=True,
8     separators=(",", ":")
9 ).encode("utf-8")
10 
11 digest = hashlib.sha256(payload).hexdigest()
12 print("计算值:", digest)
13 print("签名值:", bundle["record_attestation"]["payload_sha256"])
14 assert digest == bundle["record_attestation"]["payload_sha256"]
06

结果判读

结果含义下一步
PASS签名、哈希或检查点核对一致继续核对下一项
INFO附加见证信息或状态提示结合证据包字段阅读
FAIL文件内容、签名或检查点不一致重新下载原始证据包并复核来源
未找到记录日志尚未同步或 Request ID 输入不完整等待几分钟后使用完整 ID 重试
07

常见问题排查

问题处理
查询一直显示核查中保留当前页面，等待日志分页同步完成后重新点击查询
浏览器不支持本地验签下载证据包，使用上面的 Python 离线验证命令
Request ID 被截断从原始响应头复制完整值
模型字段不一致在证据包中对照 model_name、forwarded_model 和 model_mapping
需要保存审计材料同时保存原始响应头、证据包、验证器输出和验证时间
开始验证请求 返回 API 接入文档 查看公开验签密钥
已复制