API 文档
本站提供三类接口：公开 API（无需登录）、账户 API（需登录 Cookie）、以及 API Key（v1）接口（需密钥）。 当前为预览能力，正式计费与套餐以后续公告为准。
目录
基础地址
所有路径均相对于站点根 URL，例如 http://localhost:3000。
公开 API（无需登录）
这些接口可直接调用，主要用于工具页展示；通常会代理第三方数据源，并做基础校验与超时保护。
返回可用货币列表（来自 Frankfurter）。
返回最新汇率（校验 3 位大写货币代码）。成功返回：{ date, from, to, rate, source }。
金属现货参考价（USD + 按 USD/CNY 换算 CNY），包含克价字段。成功返回：{ usdCnyRate, rows: [...] }。
返回热门工具榜单（按周期统计的热度）。成功返回：{ period, rows: [{ slug, title, heat, rank }] }。
返回访问者公网 IP 推断的 IANA 时区。成功返回：{ timezone, source }（失败则 timezone 为 null）。
首页轮播广告数据（若未配置或不可用，返回空数组）。
错误码约定（公开 API）
400：参数不合法（例如货币代码格式错误）502：上游服务不可用/超时/数据格式异常
账户 API（需登录）
这些接口用于站内账户功能，基于浏览器 Cookie 会话鉴权（不是 API Key）。若未登录通常返回 401。
列出当前用户未撤销的 API Key（不含明文）。
创建 API Key。请求体：{ name?: string }。成功返回包含 key（仅此一次可见）。
修改昵称与头像 URL。请求体：{ name, image? }。
点赞/取消点赞工具。请求体：{ toolSlug }，返回 { liked, totalLikes }。
API Key（v1）接口（需密钥）
请求头任选其一（不要同时使用多种方式混传多把密钥）：Authorization: Bearer <完整密钥>或X-Api-Key: <完整密钥>
密钥须以 sk_live_ 开头，在 API 密钥 页面创建；服务端仅保存哈希，明文仅创建时展示一次。
配额与审计
- 每把密钥按 UTC 自然日 计数；默认每日最多 10000 次消耗型调用（由
API_DAILY_LIMIT_PER_KEY控制）。 /api/v1/echo消耗 1 次；/api/v1/status不消耗。- 调用会写入审计日志，可在「API 调用日志」中查看。
校验密钥并返回示例 JSON；消耗配额。返回：{ ok, endpoint, userId, usage }。
返回当前 UTC 日用量与上限；不消耗配额。返回：{ ok, endpoint, usage }。
错误响应（v1）
401—{ "error": "unauthorized" }429—{ "error": "quota_exceeded", "limit": <number> }500—{ "error": "server_error" }
示例
将 <密钥> 替换为真实 Key。
curl -sS -H "Authorization: Bearer <密钥>" \ "http://localhost:3000/api/v1/echo" curl -sS -H "X-Api-Key: <密钥>" \ "http://localhost:3000/api/v1/status"
const r = await fetch("http://localhost:3000/api/v1/echo", {
headers: { Authorization: "Bearer <密钥>" },
});
console.log(await r.json());配额与审计
每把密钥按 UTC 自然日 计数；默认每日最多 10000 次可消耗配额的调用，由环境变量 API_DAILY_LIMIT_PER_KEY 控制。超额返回 HTTP 429，响应体含 error: "quota_exceeded" 与 limit。
接入 withApiV1Auth 的路由会写入审计表，可在 API 调用日志 中按密钥与条件筛选。
端点
校验密钥并返回示例 JSON；消耗 1 次当日配额。
返回当前 UTC 日已用量与上限；不消耗 配额。
错误响应
401—{ "error": "unauthorized" }429— 配额用尽（echo 等消耗型接口）500—{ "error": "server_error" }
示例
将 <密钥> 替换为真实 Key。
curl -sS -H "Authorization: Bearer <密钥>" \ "http://localhost:3000/api/v1/echo" curl -sS -H "X-Api-Key: <密钥>" \ "http://localhost:3000/api/v1/status"
const r = await fetch("http://localhost:3000/api/v1/echo", {
headers: { Authorization: "Bearer <密钥>" },
});
console.log(await r.json());OpenAPI
机器可读规范（OpenAPI 3.0 JSON）： http://localhost:3000/api/openapi