API 参考

鉴权

所有对 /v1/* 的调用都需要一个 API Key（在控制台创建）。通过以下任一请求头传入：

• Authorization: Bearer <API_KEY>
• x-api-key: <API_KEY>

管理端点（账户、充值、API Key、通知、工单等）使用登录后的用户会话 JWT（Authorization: Bearer <token>）。

Base URL

https://api.ai.retterm.cn/v1

端点

方法	路径	说明	鉴权
GET	/v1/models	列出可用模型	API Key
POST	/v1/chat/completions	聊天补全（OpenAI 兼容）	API Key
GET	/v1/me/overview	账户概览（余额、用量）	用户会话
GET / POST / PATCH / DELETE	/v1/api-keys	管理 API Key	用户会话
POST	/v1/credits/redeem-code	兑换码充值	用户会话
GET	/v1/credits/recharge-orders	充值订单列表	用户会话
GET	/v1/notifications	通知中心	用户会话
POST	/v1/support/tickets	提交工单	用户会话
POST	/v1/auth/phone/send-code	发送手机验证码	无
POST	/v1/auth/phone/verify	手机号登录	无
GET	/health	健康检查	无

/v1/chat/completions

OpenAI 兼容请求体，常用参数：

字段	类型	说明
model	string	模型 ID（GET /v1/models 获取）
messages	array	对话消息 {role, content}
temperature	number	采样温度（可选）
top_p	number	核采样（可选）
max_tokens	number	单次最大输出 token（可选）
stream	boolean	是否流式返回（可选，默认 false）

非流式返回

{
  "id": "chatcmpl-...",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

流式

stream: true 时返回 SSE（text/event-stream），每帧含增量 delta，末尾一帧含 usage。

错误码

状态码	含义	处理
400	请求参数错误	检查请求体
401	缺少或无效 API Key	检查 token / header
402	余额不足	充值后再调用
403	无权限 / 属性不一致	检查限额、scope
404	模型或端点不存在	确认 model ID、路径
429	限流或额度用尽	退避重试 / 提高限额
5xx	上游或内部错误	稍后重试

更多排查见「常见错误」。