|
| 1 | +# RedboxWeb 接口文档（中文） |
| 2 | + |
| 3 | +更新时间：2026-03-24 |
| 4 | +适用项目：`RedboxWeb`（租户 slug=`redbox`） |
| 5 | + |
| 6 | +## 1. 基础约定 |
| 7 | + |
| 8 | +### 1.1 网关与租户 |
| 9 | +- 网关基地址：`VITE_GATEWAY_BASE_URL`，默认 `http://localhost:3000` |
| 10 | +- 租户：`VITE_APP_SLUG`，默认 `redbox` |
| 11 | +- RedboxWeb 当前默认使用租户路径：`/{app}/v1/...` |
| 12 | + |
| 13 | +示例（默认配置）： |
| 14 | +- `http://localhost:3000/redbox/v1/auth/login/sms` |
| 15 | + |
| 16 | +### 1.2 鉴权方式 |
| 17 | +- 控制台业务接口（auth/users/payments）：`Authorization: Bearer <access_token>` |
| 18 | +- OpenAI 兼容接口：`Authorization: Bearer <rbx_api_key>`（推荐）或 JWT |
| 19 | + |
| 20 | +### 1.3 响应格式 |
| 21 | +- 业务接口可能返回直接 JSON，或 `{ data: ... }` 包裹形式，前端都已兼容 |
| 22 | +- OpenAI 兼容接口错误为 OpenAI 风格： |
| 23 | +```json |
| 24 | +{ |
| 25 | + "error": { |
| 26 | + "message": "Authentication required", |
| 27 | + "type": "authentication_error", |
| 28 | + "param": null, |
| 29 | + "code": null |
| 30 | + } |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +## 2. 认证接口（注册/登录/微信） |
| 35 | + |
| 36 | +前缀：`/{app}/v1/auth` |
| 37 | + |
| 38 | +### 2.1 发送短信验证码 |
| 39 | +- `POST /auth/send-sms-code` |
| 40 | +- 请求： |
| 41 | +```json |
| 42 | +{ |
| 43 | + "phone": "13800138000" |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +### 2.2 手机号登录 |
| 48 | +- `POST /auth/login/sms` |
| 49 | +- 请求： |
| 50 | +```json |
| 51 | +{ |
| 52 | + "phone": "13800138000", |
| 53 | + "code": "123456", |
| 54 | + "invite_code": "AB12C" |
| 55 | +} |
| 56 | +``` |
| 57 | +- 返回：`access_token`、`refresh_token`、`user` 等 |
| 58 | + |
| 59 | +### 2.3 手机号注册（兼容别名） |
| 60 | +- `POST /auth/register/sms` |
| 61 | +- 行为与短信登录一致：首次建号，后续即登录 |
| 62 | + |
| 63 | +### 2.4 获取微信扫码登录信息 |
| 64 | +- `GET /auth/login/wechat/url?state=redbox-web` |
| 65 | +- 返回关键字段： |
| 66 | + - `enabled` |
| 67 | + - `session_id` |
| 68 | + - `qr_content_url` |
| 69 | + - `url` |
| 70 | + - `expires_in` |
| 71 | + |
| 72 | +### 2.5 轮询微信扫码状态 |
| 73 | +- `GET /auth/login/wechat/status?session_id=<session_id>` |
| 74 | +- 状态：`PENDING | SCANNED | CONFIRMED | EXPIRED | FAILED` |
| 75 | +- `CONFIRMED` 时会返回 `auth_payload`（含 token） |
| 76 | + |
| 77 | +### 2.6 微信 code 登录（回调后换取登录态） |
| 78 | +- `POST /auth/login/wechat` |
| 79 | +- 请求： |
| 80 | +```json |
| 81 | +{ |
| 82 | + "code": "wechat_oauth_code" |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +说明： |
| 87 | +- 微信开放平台回调到你的 `redirect_uri` 页面后，前端拿到 `code`，再调用此接口完成登录。 |
| 88 | + |
| 89 | +## 3. 用户与 API Key 接口 |
| 90 | + |
| 91 | +前缀：`/{app}/v1/users` |
| 92 | + |
| 93 | +### 3.1 获取当前用户 |
| 94 | +- `GET /users/me` |
| 95 | + |
| 96 | +### 3.2 获取积分余额与计费规则 |
| 97 | +- `GET /users/me/points` |
| 98 | + |
| 99 | +### 3.3 列出我的 API Keys |
| 100 | +- `GET /users/me/api-keys` |
| 101 | + |
| 102 | +### 3.4 创建 API Key |
| 103 | +- `POST /users/me/api-keys` |
| 104 | +- 请求： |
| 105 | +```json |
| 106 | +{ |
| 107 | + "name": "Production Key" |
| 108 | +} |
| 109 | +``` |
| 110 | +- 返回中 `key` 明文只会出现一次 |
| 111 | + |
| 112 | +### 3.5 撤销 API Key |
| 113 | +- `POST /users/me/api-keys/:key_id/revoke` |
| 114 | + |
| 115 | +## 4. 支付与充值接口 |
| 116 | + |
| 117 | +前缀：`/{app}/v1/payments` |
| 118 | + |
| 119 | +### 4.1 获取可购买商品 |
| 120 | +- `GET /payments/products` |
| 121 | +- 关键字段： |
| 122 | + - `amount`：商品金额 |
| 123 | + - `points_topup`：支付成功后自动充值的积分 |
| 124 | + |
| 125 | +### 4.2 创建支付宝 page-pay 订单 |
| 126 | +- `POST /payments/orders/page-pay` |
| 127 | +- 请求： |
| 128 | +```json |
| 129 | +{ |
| 130 | + "product_id": "uuid", |
| 131 | + "subject": "30元积分包", |
| 132 | + "points_to_deduct": 0 |
| 133 | +} |
| 134 | +``` |
| 135 | +- 返回关键字段： |
| 136 | + - `out_trade_no` |
| 137 | + - `payment_form`（可能是 HTML form 或 URL） |
| 138 | + - `amount`、`original_amount`、`payable_amount` |
| 139 | + |
| 140 | +### 4.3 创建微信 Native 支付订单（可选） |
| 141 | +- `POST /payments/orders/wechat/native` |
| 142 | +- 请求： |
| 143 | +```json |
| 144 | +{ |
| 145 | + "product_id": "uuid", |
| 146 | + "description": "30元积分包" |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +### 4.4 查询订单状态 |
| 151 | +- `GET /payments/orders/:out_trade_no` |
| 152 | +- 返回关键字段： |
| 153 | + - `status` |
| 154 | + - `trade_status` |
| 155 | + - `paid_at` |
| 156 | + - `points_topup_points` |
| 157 | + - `points_topup_status`（`NONE | PROCESSING | SUCCESS`） |
| 158 | + |
| 159 | +### 4.5 支付回调接口（服务端/支付渠道调用，前端一般不直接调用） |
| 160 | +- 支付宝异步通知：`POST /payments/callbacks/trade-notify` |
| 161 | +- 支付宝同步回跳：`GET /payments/callbacks/trade-return` |
| 162 | +- 支付宝签约回调：`POST /payments/callbacks/agreement-notify` |
| 163 | +- 微信支付回调：`POST /payments/callbacks/wechat-notify` |
| 164 | + |
| 165 | +## 5. OpenAI 兼容接口（调用 AI） |
| 166 | + |
| 167 | +前缀可选： |
| 168 | +- `/v1/...`（推荐给 API Key 调用） |
| 169 | +- `/{app}/v1/...` |
| 170 | +- `/api/v1/...` |
| 171 | + |
| 172 | +支持能力： |
| 173 | +- 语言模型：`POST /chat/completions`、`POST /completions`、`POST /responses` |
| 174 | +- 模型列表：`GET /models`、`GET /models/:model` |
| 175 | +- 嵌入模型：`POST /embeddings` |
| 176 | +- 音频生成（TTS）：`POST /audio/speech` |
| 177 | +- 转录/翻译（STT）：`POST /audio/transcriptions`、`POST /audio/translations` |
| 178 | +- 图片生成：`POST /images/generations` |
| 179 | + |
| 180 | +### 5.1 拉取所有可用模型 |
| 181 | +- `GET /v1/models` |
| 182 | +- 示例： |
| 183 | +```bash |
| 184 | +curl -X GET "$BASE_URL/v1/models" \ |
| 185 | + -H "Authorization: Bearer $RBX_API_KEY" |
| 186 | +``` |
| 187 | + |
| 188 | +### 5.2 拉取单个模型详情 |
| 189 | +- `GET /v1/models/{model}` |
| 190 | + |
| 191 | +### 5.3 Chat Completions 示例 |
| 192 | +```bash |
| 193 | +curl -X POST "$BASE_URL/v1/chat/completions" \ |
| 194 | + -H "Authorization: Bearer $RBX_API_KEY" \ |
| 195 | + -H "Content-Type: application/json" \ |
| 196 | + -d '{ |
| 197 | + "model": "gpt-4o-mini", |
| 198 | + "messages": [{"role":"user","content":"你好"}] |
| 199 | + }' |
| 200 | +``` |
| 201 | + |
| 202 | +### 5.4 Embeddings 示例 |
| 203 | +```bash |
| 204 | +curl -X POST "$BASE_URL/v1/embeddings" \ |
| 205 | + -H "Authorization: Bearer $RBX_API_KEY" \ |
| 206 | + -H "Content-Type: application/json" \ |
| 207 | + -d '{ |
| 208 | + "model": "text-embedding-3-small", |
| 209 | + "input": "hello world" |
| 210 | + }' |
| 211 | +``` |
| 212 | + |
| 213 | +### 5.5 音频转录示例（JSON base64） |
| 214 | +```bash |
| 215 | +curl -X POST "$BASE_URL/v1/audio/transcriptions" \ |
| 216 | + -H "Authorization: Bearer $RBX_API_KEY" \ |
| 217 | + -H "Content-Type: application/json" \ |
| 218 | + -d '{ |
| 219 | + "model": "whisper-1", |
| 220 | + "file_base64": "<base64>", |
| 221 | + "file_name": "demo.wav", |
| 222 | + "file_mime_type": "audio/wav" |
| 223 | + }' |
| 224 | +``` |
| 225 | + |
| 226 | +### 5.6 图片生成示例 |
| 227 | +```bash |
| 228 | +curl -X POST "$BASE_URL/v1/images/generations" \ |
| 229 | + -H "Authorization: Bearer $RBX_API_KEY" \ |
| 230 | + -H "Content-Type: application/json" \ |
| 231 | + -d '{ |
| 232 | + "model": "gpt-image-1", |
| 233 | + "prompt": "A red robot in watercolor style", |
| 234 | + "size": "1024x1024" |
| 235 | + }' |
| 236 | +``` |
| 237 | + |
| 238 | +## 6. RedboxWeb 当前实际使用到的接口 |
| 239 | + |
| 240 | +### 6.1 登录/注册页 |
| 241 | +- `POST /auth/send-sms-code` |
| 242 | +- `POST /auth/login/sms` |
| 243 | +- `POST /auth/register/sms` |
| 244 | +- `GET /auth/login/wechat/url` |
| 245 | +- `GET /auth/login/wechat/status` |
| 246 | +- `POST /auth/login/wechat` |
| 247 | + |
| 248 | +### 6.2 控制台概览 / Keys |
| 249 | +- `GET /users/me/api-keys` |
| 250 | +- `POST /users/me/api-keys` |
| 251 | +- `POST /users/me/api-keys/:key_id/revoke` |
| 252 | + |
| 253 | +### 6.3 控制台 Billing |
| 254 | +- `GET /payments/products` |
| 255 | +- `POST /payments/orders/page-pay` |
| 256 | +- `GET /payments/orders/:out_trade_no` |
| 257 | + |
| 258 | +## 7. 推荐联调流程 |
| 259 | + |
| 260 | +1. 在 appadmin 确认已创建应用 `slug=redbox` |
| 261 | +2. 调 `POST /auth/send-sms-code` + `POST /auth/login/sms` 拿 JWT |
| 262 | +3. 调 `POST /users/me/api-keys` 创建 `rbx_` Key |
| 263 | +4. 调 `GET /payments/products`、`POST /payments/orders/page-pay`、`GET /payments/orders/:out_trade_no` 跑充值 |
| 264 | +5. 用 `rbx_` Key 调 `GET /v1/models`、`POST /v1/chat/completions` 验证 AI 链路 |
0 commit comments