认证与签名

API Key

在请求头携带以下任意一种：

• X-API-Key: <你的密钥>
• Authorization: Bearer <你的密钥>

缺少或无效的密钥返回 401 unauthorized；密钥的作用域不包含某接口时返回 403 forbidden，套餐不包含某特性时返回 403 plan_required。可以用 GET /v1/me 查看密钥的套餐、作用域与今日用量。

请求签名（Pro 及以上）

启用签名后，每个请求额外携带：

• X-Timestamp：Unix 秒级时间戳，与服务器时间相差过大会被拒绝
• X-Signature：hex(hmac_sha256(K, METHOD + "\n" + PATH + "\n" + QUERY + "\n" + TIMESTAMP))

其中 K 为签名密钥（signing secret）做 SHA-256 后的十六进制字符串，QUERY 为原始查询串（不含问号，没有则为空字符串）。

import hashlib, hmac, time

def sign(secret: str, method: str, path: str, query: str) -> tuple[str, str]:
    ts = str(int(time.time()))
    key = hashlib.sha256(secret.encode()).hexdigest().encode()
    msg = f"{method.upper()}\n{path}\n{query}\n{ts}".encode()
    return ts, hmac.new(key, msg, hashlib.sha256).hexdigest()