灵犀指IDE
中 / EN免费开始
文档中心
参考与 FAQ / 云端 REST API

云端 REST API

灵犀指云端服务提供 REST API，供 IDE 内核、官网与第三方集成调用。所有端点以 /api/v1 为前缀，默认部署于官网域名（下文以 https://www.lingxizhiai.com 为例，实际地址以你的部署配置为准）。

✦

面向谁：本文面向需要与服务端直连的开发者（CI 集成、自建工具等）。日常使用 IDE 时无需关心这些端点——内核已内置全部调用。本地内核（3721 端口）的端点清单见内核 API。

认证

除标注「公开」的端点外，均需在请求头携带 JWT Bearer 令牌：

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 完成二步验证后才能取得令牌。

认证端点

MethodPath说明
POST/auth/register注册（邮箱 + 用户名 + 密码 + 验证码）
POST/auth/login登录；MFA 账户返回中间态票据
POST/auth/mfa/verifyMFA 二步验证（票据 + 动态码/恢复码）
POST/auth/send-code发送邮箱验证码（注册/重置密码）
POST/auth/reset-password重置密码
POST/auth/refresh刷新 access token（公开，持 refresh token）

会员与订阅

MethodPath说明
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取消自己的待支付订单

积分

MethodPath说明
GET/credits/balance增购积分余额与套餐积分余量
GET/credits/ledger?limit&offset积分流水（充值/扣减/结转）
POST/credits/recharge创建增购积分订单（微信/支付宝）
GET/credits/orders/:order_no积分订单状态
GET/credits/orders积分订单列表

用量统计

MethodPath说明
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 天补全采纳率

在线支付

MethodPath说明
GET/payment/config支付渠道开关（公开）
POST/payment/orders创建支付订单（订阅或积分充值）
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": "glm-5.2", "messages": [{"role": "user", "content": "你好"}], "stream": true}'

支持 stream SSE 流式透传；扣费顺序为先套餐积分、后增购积分，积分不足时返回 402。模型清单与零售价由服务端统一管理，旗舰模型有最低套餐档位要求（见套餐与积分）。

云端任务与沙箱

MethodPath说明
POST/tasks/submit提交云端任务
GET/tasks · /tasks/:id任务列表 / 状态
POST/tasks/:id/cancel取消任务
GET/cloud/vms · /cloud/quotas云沙箱实例与配额

速率限制

登录、验证码、支付回调等敏感端点均有限流（登录类按小时计）。触发限流返回 429，部分端点会要求图形验证码。集成时请实现指数退避重试，并避免高频轮询——订单状态建议 3-5 秒间隔轮询。

下一步

← 上一篇常见问题