Public API

规范、一致的
公开 API 接口规范。

公开 API 使用 HTTPS + JSON；App 用户通过 Session Token，Beta/开发者通过 API Key。两套调用方式最终按 userId 共享会员和用量检查。

01 / 认证请求头

三种请求头，最终进入同一个鉴权上下文。

鉴权中间件通过短路求值保留明确的优先级：Session 失败不回退，API Key 推荐使用 X-API-Key。

身份主体 (Identity)	请求头格式 (Header)	用途与鉴权逻辑 (Usage & Context)
Session Token	`Authorization: Bearer sp_sess_xxx`	StudyPulse App / Web 登录用户；绑定 userId 和会员额度。
API Key (推荐)	`X-API-Key: sp_beta_xxx`	Beta / 开发者调用；按 Key 和绑定用户双重计量。
API Key (Legacy)	`Authorization: Bearer sp_beta_xxx`	兼容旧版客户端的 API Key 传递方式。

02 / 核心接口

文本、多模态与 SSE，走同一条入口。

content 数组优先级高于 message；model 默认 MiniMax-M3，客户端不能覆盖 provider 的 endpoint 和 thinking 配置。

统一代理 MiniMax-M3 流式多模态调用

POST /v1/chat 是 StudyPulse 客户端的核心 AI 接口。请求支持单轮或多轮消息、图文混合内容，并通过 Server-Sent Events (SSE) 实时推流返回给客户端。

所有的 Token 计量只在 SSE 流完成或全量响应成功返回后异步落库，绝不阻塞流式传输管道。

                                POST /v1/chat
                                application/json · text/event-stream
                            
curl -X POST https://spapi.chenkai.space/v1/chat   -H "X-API-Key: sp_beta_xxx"   -H "Content-Type: application/json"   -d '{
    "content": [
      {"type":"text","text":"描述这张错题图"},
      {"type":"image_url","image_url":{"url":"https://…"}}
    ],
    "stream": true
  }'

// response: text/event-stream
data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[],"usage":{"total_tokens":60}}
data: [DONE]

03 / 端点地图

公开接口与用户/管理接口分层。

公开 API 面向 AI 调用；统一身份中心只接受 Session；管理员状态变更还需要 CSRF Token。

GET /

健康检查，无鉴权。

POST /auth/send-code

发送登录、注册或重置密码验证码。

POST /auth/login/password

邮箱 + 密码登录，成功后创建统一 Session。

POST /auth/refresh

单次轮换 Refresh Token，旧 Token 立即失效。

GET /v1/auth/me

返回用户基础信息与登录方式，不返回密钥。

GET /user/profile

返回用户信息、会员计划和当前用量。

GET /api/admin/stats

管理员仪表盘统计：Key、用户、请求与超额。

POST /api/admin/keys/create

创建 Key；原始 rawKey 只返回一次。

04 / 错误与配额

标准 HTTP 状态码与结构化错误响应。

鉴权、额度、上游错误和认证错误都有明确的 HTTP 状态与机器可读信息，便于 iOS 客户端区分重试、重新登录和升级会员。

HTTP 状态码	代表错误 (Error Code)	处理语义与建议动作 (Handling)
400	`Invalid JSON Body` / `INVALID_EMAIL`	客户端修正输入后重试。
401	`SESSION_EXPIRED`	使用 Refresh Token；刷新失败则重新登录。
403	`API Key disabled`	停止重试，提示 Key 状态或权限问题。
429	`Daily request limit exceeded`	等待配额窗口重置，或升级 free / plus / pro 计划。
502	`AI request failed`	上游 MiniMax 失败；不计入额度。