feat: associate generation calls with devices
This commit is contained in:
QiuSW
+15
-2
@@ -18,7 +18,7 @@
|
||||
- T-608 起新用户注册成功一次性赠送 **10 点**试用点数；赠点必须经计费层写入钱包和 `PointsLedger(change_type=signup_bonus)`，不得直接改余额字段。历史用户是否补发不属于默认注册流程。
|
||||
- API Key 库内只存 `key_hash`（SHA-256）与 `key_prefix`，明文只在创建时返回一次，不在 admin、日志或调用记录中回显。
|
||||
- 每次生成调用写 `CallRecord`；只允许保存 `result_ref` / `result_summary` 这类引用或摘要，不保存 provider `raw`、base64 图片或敏感上游字段。
|
||||
- T-624 起，蝦皮圈客户端可先用 API Key 登记设备并取得短期 `X-Device-Session`；设备会话仅用于设备心跳，尚**不**参与现有生成/余额接口鉴权、计费或授权拦截。设备标识、公钥和会话令牌不写入调用日志或响应中的设备对象。
|
||||
- T-624/T-625 起，蝦皮圈客户端可先用 API Key 登记设备并取得短期 `X-Device-Session`；标题、图片、异步图片提交和图片理解可选携带该头，服务端只把已验证的设备关联到本次 `CallRecord` 与白名单遥测。没有该头的旧客户端继续按原 API Key 路径调用，响应、计费、任务提交和轮询均不变；设备会话尚**不**参与订阅授权拦截。设备标识、公钥和会话令牌不写入调用日志或响应中的设备对象。
|
||||
|
||||
T-301 已实现对外 API 鉴权基线：`apps.api.authentication.ApiKeyAuthentication` 只解析 `Authorization: Bearer <API_KEY>`；生成、余额等外部 API 视图应继承 `apps.api.views.ExternalApiView`，不接受 Web session。
|
||||
|
||||
@@ -91,6 +91,7 @@ T-607/T-609/T-617 已实现 `GET /api/v1/client/releases/latest?platform=windows
|
||||
| `rate_limited` | 请求过于频繁，请稍后再试 | 429 |
|
||||
| `device_session_invalid` | 缺失、无效或过期设备会话 | 401 |
|
||||
| `device_revoked` | 客户端设备已被吊销 | 403 |
|
||||
| `device_mismatch` | 设备会话不属于当前 API Key 所属账号 | 403 |
|
||||
| `device_identity_mismatch` | 同一设备标识对应的安装公钥不一致 | 403 |
|
||||
|
||||
`upstream_timeout` 与 `upstream_error` 都表示本次生成失败且已退点，客户端可按失败 / 重试处理。`upstream_timeout` 通常来自 T-612 的生图上游硬截止或底层 HTTP 超时。`upstream_error` 需要按错误消息继续区分：如果 `/api/v1/balance` 成功、`/api/v1/models` 中目标别名存在且 `pricing_status="priced"`，但生成接口返回 `502 upstream_error` 且消息为「上游模型配置不可用」，优先判定为**服务端上游模型运行配置问题**，不是客户端 payload 问题。常见原因是 `AI_KEY_ENCRYPTION_KEY` 与入库时不一致、`AiModel.api_key_encrypted` 无法解密、别名指向的 `AiModel` 缺 `url` / `model` / `api_type` / API Key，或 `api_type` 无可用 Provider。该错误路径不应最终扣点；修复按 [`deployment.md`](deployment.md) 的 AI 模型配置排查步骤执行。
|
||||
@@ -194,6 +195,16 @@ X-Device-Session: dvs_cmhub_<device_session_token>
|
||||
|
||||
成功响应返回当前设备公开摘要、会话到期时间和 `activity_updated`。默认同一设备至少间隔 24 小时才写入一次 `last_seen_at`，因此频繁心跳可能返回 `activity_updated=false`，这是正常行为。缺失、无效或过期会话返回 `401 device_session_invalid`；已吊销设备返回 `403 device_revoked`。该接口不扣点、不创建调用记录，也不刷新过期会话；客户端应重新调用登记接口获取新令牌。
|
||||
|
||||
### 生成接口的可选设备会话
|
||||
|
||||
以下生成提交路由可在既有 `Authorization: Bearer <API_KEY>` 外，额外携带同账号登记得到的设备会话：`POST /api/v1/generate/title`、`POST /api/v1/analyze/images`、`POST /api/v1/generate/image`、`POST /api/v1/generate/image/tasks`。
|
||||
|
||||
```http
|
||||
X-Device-Session: dvs_cmhub_<device_session_token>
|
||||
```
|
||||
|
||||
会话有效时，服务端将对应 `ClientDevice` 写入本次调用记录；不会把设备原始标识、公钥、会话明文、prompt 或图片写入用量日志。未携带该头时保留存量 API 契约和账务语义。调用方一旦携带该头，伪造或过期会话返回 `401 device_session_invalid`，已吊销设备或跨账号会话返回 `403 device_revoked` / `403 device_mismatch`，且请求在预扣前被拒绝。异步任务的后续 `GET` 轮询不需要该头，仍只按 API Key 所属用户校验任务归属。
|
||||
|
||||
### `POST /api/v1/generate/title`
|
||||
|
||||
生成标题。请求：
|
||||
@@ -270,9 +281,10 @@ X-Device-Session: dvs_cmhub_<device_session_token>
|
||||
|
||||
```http
|
||||
X-Client-Version: 0.1.1
|
||||
X-Device-Session: dvs_cmhub_<device_session_token>
|
||||
```
|
||||
|
||||
该字段仅用于 T-615 的用量遥测，帮助服务端区分旧同步接口由哪些客户端版本调用；不影响响应结构。
|
||||
`X-Client-Version` 仅用于 T-615 的用量遥测，帮助服务端区分旧同步接口由哪些客户端版本调用；不影响响应结构。`X-Device-Session` 为 T-625 可选设备关联头，省略时保持旧客户端行为。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -326,6 +338,7 @@ POST /api/v1/generate/image/tasks
|
||||
Authorization: Bearer sk_cmhub_xxx
|
||||
Idempotency-Key: desktop-job-20260708-0001
|
||||
X-Client-Version: 0.1.1
|
||||
X-Device-Session: dvs_cmhub_<device_session_token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user