Lune Research API 服务协议

REST API 不是受支持的公开接入方式。网页聊天应用请安装 Lune 连接器或插件，本地 Agent 请添加 MCP 服务器。不要直接向 api.luneresearch.com 发送科研请求。

Lune 公开这份协议，是为了让运营方能够检查官方 MCP 服务器、CLI 和控制台使用的底层服务。版本、弃用、错误和限流约定也统一记录在这里。

版本约定

REST 主版本写在 URL 中。向后兼容的新增内容会继续留在当前主版本，例如新增可选响应字段、新增端点，以及省略后仍保持原有行为的可选请求参数。删除或重命名字段、改变字段含义或类型、把可选输入改为必填，或改变现有状态语义，都必须使用 /api/v2 这样的新主版本路径。

计划停止兼容的接口时，Lune 会至少提前 180 天公布日落日期。弃用期间，响应会同时提供以下信号：

Deprecation: @1782863999
Sunset: Wed, 30 Dec 2026 23:59:59 GMT
Link: <https://luneresearch.com/docs/api>; rel="deprecation"

Deprecation 遵循 RFC 9745，使用 Structured Fields 日期。Sunset 遵循 RFC 8594，使用 HTTP 日期。日落时间绝不会早于弃用时间。链接的政策页面会说明替代接口和迁移步骤。Lune API v1 目前没有弃用，因此当前 v1 响应不会包含这两个日期字段。

限流字段

短时突发保护会按团队或客户端 IP 计算。限流保护记录了实时状态时，请求会返回当前 IETF HTTPAPI 字段格式：

RateLimit-Policy: "burst";q=30;w=1
RateLimit: "burst";r=29;t=1

q 是政策额度，w 是秒级窗口，r 是当前请求完成后的可用额度，t 是有效窗口剩余秒数。可公开缓存的响应只公布静态政策，避免共享缓存重放另一位访问者的剩余值。计数器不可用而放行请求时也只公布静态政策。所有触发限流的 429 都会公布剩余值为零和重试时间。

触发限流时，API 返回 429 Too Many Requests，并同时提供剩余值和 Retry-After：

RateLimit: "burst";r=0;t=1
Retry-After: 1

套餐的每日额度与一秒突发保护相互独立。你可以通过 /api/v1/account/whoami 查询每日额度。如果一项计费调用同时超出每日额度和预付点数，API 会返回带类型响应体的 402 Payment Required，告诉调用方应该停止、缩小批次后重试，还是因为额度刚刚恢复而原样重试一次。402 不会提供 Retry-After。

错误

先判断 HTTP 状态，再读取 JSON 响应体中的机器字段。鉴权失败返回 401。权限不足返回 403，并列出 required 和 granted。额度耗尽返回 402。突发限流返回 429。输入校验失败返回 422，其中包含带类型的字段位置。OAuth Token 端点按 RFC 6749 使用扁平的 error 和 error_description 结构。

客户端身份

Lune 官方 MCP 服务器和 CLI 会发送 X-Lune-Client，这样用量日志不读取工具输入或响应内容，也能区分官方客户端。这个字段只用于运行记录，不代表 Lune 支持直接构建 REST 客户端。