接入与调用

支持跨域（CORS）调用吗？

开放接口一律返回 Access-Control-Allow-Origin: *，浏览器可直接调用。但这意味着你的密钥会出现在前端——所以浏览器端调用只适合公开端点（如 /api/signing-keys/*）；带密钥的调用请由你的服务端中转。

必须带什么头？

v1 家族必须带 Authorization: Bearer <密钥>；POST 建议再带 Content-Type: application/json 与 Idempotency-Key。

有没有 SDK？

官方暂不发 SDK。接口是标准 REST + JSON，任何能发 HTTP 的语言都能用；也可以把 openapi.json 导入 openapi-generator 生成你自己的客户端。

鉴权与密钥

401 的两种错误码为什么分不出「没带」和「带错了」？

刻意如此。若两者返回不同结果，就能用接口试探某个密钥是否存在/是否有效。请按「补一个有效密钥」处理，不要靠它做分支判断。

developer / shared-index 用什么令牌？

用 QuickFind 用户登录后的会话 JWT，放在同一个 Authorization: Bearer 头里。它不是 API 密钥，会随登出失效，不适合长期跑批——长期任务请用 v1 家族。

配额与限流

被限流后要等多久？

看响应体的 retry_after（秒），或 RateLimit-Retry-After 响应头。建议指数退避 + 抖动，不要在固定间隔重试。

从 www 和 api 同时调用会双倍计费吗？

不会。两个入口主机共享同一套全局计数（按密钥摘要与 IP），同一个请求只算一次。

数据边界

能读取我电脑上的文件索引吗？

不能，以后也不会。文件索引只留在本机，接口只碰云端数据（账号、订单、订阅、提交记录等）。这是产品边界，不是「尚未实现」。

响应会被缓存吗？

/api/ 下所有响应都带 Cache-Control: no-store, must-revalidate，不会被任何中间层缓存。高频只读场景请在你自己的服务侧做缓存。

搜索由全站搜索站提供，覆盖官网、文档与门户内容。