云端 REST API
灵犀指云端服务提供 REST API，供 IDE 内核、官网与第三方集成调用。所有端点以 /api/v1 为前缀（下文域名仅为示例，实际地址以部署配置为准）。端点可用性取决于服务部署、账号权限、支付渠道和资源配置，不代表公有云服务持续在线。模型请求会经过网关发送所选上下文到厂商。
面向谁：本文面向需要与服务端直连的开发者（CI 集成、自建工具等）。日常 IDE 功能由客户端及内核按配置调用相关端点，不代表覆盖全部服务接口。本地内核端点清单见内核 API。
认证
用户受保护端点需在请求头携带 JWT Bearer 令牌。注册、登录、邮箱验证码和密码重置不要求用户 JWT；MFA 验证使用登录票据；支付回调由支付平台调用并在服务端验签，不使用用户 JWT：
curl -H "Authorization: Bearer <access_token>" https://www.lingxizhiai.com/api/v1/membership/current
令牌通过 /auth/login 获取，有效期结束前用 refresh token 调 /auth/refresh 续期。启用 MFA 且服务端已配置所需依赖时，登录会返回 mfa_required + mfa_ticket，需再调 /auth/mfa/verify 完成二步验证后才能取得令牌；MFA 端点注册取决于部署条件。
认证端点
| Method | Path | 说明 |
|---|---|---|
| POST | /auth/register | 注册（邮箱 + 用户名 + 密码 + 验证码） |
| POST | /auth/login | 登录；MFA 账户返回中间态票据 |
| POST | /auth/mfa/verify | MFA 二步验证（票据 + 动态码/恢复码） |
| POST | /auth/send-code | 发送邮箱验证码（注册/重置密码） |
| POST | /auth/reset-password | 重置密码 |
| POST | /auth/refresh | 刷新 access token（受保护，以 refresh token 作为 Bearer） |
会员与订阅
| Method | Path | 说明 |
|---|---|---|
| GET | /membership/plans | 套餐目录（公开，营销页动态定价来源） |
| GET | /membership/current | 当前会员状态（含积分余额） |
| POST | /membership/subscribe | 创建订阅订单（待支付） |
| POST | /membership/upgrade | 升级到更高档位（剩余积分全额结转） |
| POST | /membership/cancel | 取消订阅（周期结束后降为免费版） |
| GET | /membership/quota | 配额检查 |
| GET | /membership/usage?days=30 | 订阅用量（按日） |
| GET | /membership/orders | 订单列表 |
| POST | /membership/orders/:order_no/cancel | 取消自己的待支付订单 |
创建订阅或升级订单不代表权益已开通；支付确认并完成权益更新后生效。支付渠道不可用时联系支持，云资源还需对应服务部署。
积分
| Method | Path | 说明 |
|---|---|---|
| GET | /credits/balance | 增购积分余额与套餐积分余量 |
| GET | /credits/ledger?limit&offset | 积分流水（充值/扣减/结转） |
| POST | /credits/recharge | 创建增购积分订单（微信/支付宝） |
| GET | /credits/orders/:order_no | 积分订单状态 |
| GET | /credits/orders | 积分订单列表 |
用量统计
| Method | Path | 说明 |
|---|---|---|
| GET | /usage/logs?limit&offset | 调用日志明细 |
| GET | /usage/stats?days=7 | 用量汇总（请求数、Token、缓存节省） |
| GET | /usage/daily?days=30 | 按日用量 |
| GET | /usage/models?days=30 | 按模型统计 |
| GET | /usage/cost?days=30 | 费用统计 |
| GET | /usage/completions | 近 30 天补全采纳率 |
在线支付
| Method | Path | 说明 |
|---|---|---|
| GET | /payment/config | 支付渠道开关（公开） |
| POST | /payment/orders | 创建支付订单（订阅或升级；积分充值使用 /credits/recharge） |
| GET | /payment/orders/:order_no | 订单状态轮询 |
| POST | /payment/notify/:channel | 渠道异步回调（平台间调用，验签在服务端） |
LLM 官方托管池网关（OpenAI 兼容）
官方托管池提供 OpenAI 兼容的对话接口——免 BYOK，按积分计费。使用用户 access token 作为 Bearer：
curl https://www.lingxizhiai.com/api/v1/llm/gateway/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"model": "<model-id-from-catalog>", "messages": [{"role": "user", "content": "你好"}], "stream": true}'
将 <model-id-from-catalog> 替换为当前账号模型目录中的 ID；不要假定固定型号或权限。
支持 stream SSE 流式透传；扣费顺序为先增购积分、后套餐积分，积分不足时返回 402。模型清单与零售价由服务端统一管理，可用模型与最低套餐要求以当前目录及账号权限为准（见套餐与积分）。
云端任务与沙箱
| Method | Path | 说明 |
|---|---|---|
| POST | /tasks/submit | 提交云端任务 |
| GET | /tasks · /tasks/:id | 任务列表 / 状态 |
| POST | /tasks/:id/cancel | 取消任务 |
| GET | /cloud/vms · /cloud/quotas | 云沙箱实例与配额 |
速率限制
敏感端点的限流窗口与验证要求以部署配置及响应为准。触发限流可能返回 429，部分端点会要求图形验证码。集成时请实现指数退避重试，并避免高频轮询——订单状态建议 3-5 秒间隔轮询。
下一步
- 本地内核端点（使用实际连接地址）速查表：内核 API。
- 套餐档位与模型门控：套餐与积分。
- 自备厂商 Key 直连：自带 API Key。