170 lines
4.7 KiB
Markdown
170 lines
4.7 KiB
Markdown
# CozSweet 多角色聊天前端对接
|
|
|
|
## 3. Character IDs
|
|
|
|
前端先调用：
|
|
|
|
```http
|
|
GET <API_BASE_URL>/api/characters?capability=chat
|
|
```
|
|
|
|
聊天业务统一使用响应里的 `items[].id`。当前规范 ID 是：
|
|
|
|
```text
|
|
elio
|
|
maya-tan
|
|
nayeli-cervantes
|
|
```
|
|
|
|
只允许传递角色目录响应中的 `items[].id`，不要传展示名或 `@handle`。
|
|
|
|
角色响应中的 `capabilities` 是后端权威开关。`chat=false` 时不得开放输入框；直接调用聊天接口会得到 `CHARACTER_DISABLED`，不会返回 Elio 历史。
|
|
|
|
## 4. Send Message
|
|
|
|
### Request URL
|
|
|
|
```http
|
|
POST <API_BASE_URL>/api/chat/send
|
|
Content-Type: application/json
|
|
Authorization: Bearer <TOKEN>
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Field | Type | Required | Example | Meaning |
|
|
| --- | --- | --- | --- | --- |
|
|
| `characterId` | string | 新前端必传 | `maya-tan` | 当前聊天角色 ID |
|
|
| `message` | string | 与图片至少一项有值 | `Hello Maya` | 用户文本，最多 4000 字符 |
|
|
| `imageId` | string | 否 | `abc123` | 上传图片 ID |
|
|
| `imageThumbUrl` | string | 否 | `/images/...` | 缩略图 |
|
|
| `imageMediumUrl` | string | 否 | `/images/...` | 模型识图使用 |
|
|
| `imageOriginalUrl` | string | 否 | `/images/...` | 原图 |
|
|
| `imageWidth` | integer | 否 | `1080` | 图片宽 |
|
|
| `imageHeight` | integer | 否 | `1440` | 图片高 |
|
|
| `useWebSocket` | boolean | 否 | `false` | 是否同时通过已连接 WS 推送 |
|
|
|
|
```bash
|
|
curl -X POST 'https://proapi.banlv-ai.com/api/chat/send' \
|
|
-H 'Authorization: Bearer <TOKEN>' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"characterId":"maya-tan","message":"Hello Maya","useWebSocket":false}'
|
|
```
|
|
|
|
响应沿用现有发送结构。前端仍读取 `data.reply`、`data.messageId`、`data.audioUrl`、`data.image` 和 `data.lockDetail`，无需从响应推断角色。
|
|
|
|
## 5. Chat History
|
|
|
|
```http
|
|
GET <API_BASE_URL>/api/chat/history?characterId=maya-tan&limit=50&offset=0
|
|
Authorization: Bearer <TOKEN>
|
|
```
|
|
|
|
| Query | Type | Required | Rule |
|
|
| --- | --- | --- | --- |
|
|
| `characterId` | string | 新前端必传 | 只返回该角色数据 |
|
|
| `limit` | integer | 否 | `1-200`，默认 `50` |
|
|
| `offset` | integer | 否 | 最小 `0` |
|
|
|
|
`messages` 和 `total` 都只统计指定角色。切换角色时必须重新请求 history，不能复用上一个角色的本地数组。
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"success": true,
|
|
"message": "success",
|
|
"data": {
|
|
"messages": [
|
|
{
|
|
"role": "user",
|
|
"type": "text",
|
|
"content": "Hello Maya",
|
|
"id": "<MESSAGE_ID>",
|
|
"created_at": "2026-07-17T09:00:00Z",
|
|
"audioUrl": null,
|
|
"image": {"type": null, "url": null},
|
|
"lockDetail": {"locked": false, "showContent": true, "showUpgrade": false}
|
|
}
|
|
],
|
|
"total": 1,
|
|
"limit": 50,
|
|
"offset": 0,
|
|
"isVip": false
|
|
}
|
|
}
|
|
```
|
|
|
|
## 6. Latest Previews
|
|
|
|
角色会话列表可一次请求所有可聊天角色的最后一条消息：
|
|
|
|
```http
|
|
GET <API_BASE_URL>/api/chat/previews
|
|
Authorization: Bearer <TOKEN>
|
|
```
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"success": true,
|
|
"data": {
|
|
"items": [
|
|
{"characterId": "elio", "message": {"id": "...", "role": "assistant", "type": "text", "content": "..."}},
|
|
{"characterId": "maya-tan", "message": null}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
锁定私密文本不会泄露内容，锁定语音不会返回 `audioUrl`（文字仍正常返回）。图片沿用现有协议，URL 可以存在；前端必须以 `lockDetail.locked=true` 覆盖展示，不能把“URL 非空”当作已解锁。
|
|
|
|
## 7. Unlock One Message
|
|
|
|
```http
|
|
POST <API_BASE_URL>/api/chat/unlock-private
|
|
Content-Type: application/json
|
|
Authorization: Bearer <TOKEN>
|
|
```
|
|
|
|
```json
|
|
{
|
|
"characterId": "maya-tan",
|
|
"messageId": "<MESSAGE_ID>",
|
|
"lockType": "voice_message",
|
|
"clientLockId": "maya-card-001"
|
|
}
|
|
```
|
|
|
|
`messageId` 存在时，后端会核对消息角色。拿 Elio 的 `messageId` 配 Maya 的 `characterId` 会返回 HTTP `409 / CHARACTER_MISMATCH`，且不会扣积分。
|
|
|
|
前端临时伪造锁卡片没有 `messageId` 时，仍传 `characterId + lockType + clientLockId`。`clientLockId` 的幂等查找范围已包含账号和角色，同一个 ID 可以在不同角色下分别使用。
|
|
|
|
## 8. Unlock Current Character History
|
|
|
|
```http
|
|
POST <API_BASE_URL>/api/chat/unlock-history
|
|
Content-Type: application/json
|
|
Authorization: Bearer <TOKEN>
|
|
```
|
|
|
|
```json
|
|
{"characterId":"maya-tan"}
|
|
```
|
|
|
|
费用、锁消息数量、成功解锁数量及 `messageIds` 都只计算当前角色。钱包余额仍是账号全局余额。
|
|
|
|
## 12. Tip Attribution
|
|
|
|
只有 Tip 订单使用角色归属：
|
|
|
|
```json
|
|
{
|
|
"planId": "tip_coffee_usd_4_99",
|
|
"payChannel": "stripe",
|
|
"autoRenew": false,
|
|
"recipientCharacterId": "maya-tan"
|
|
}
|
|
```
|
|
|
|
Tip 订单必须携带 `recipientCharacterId`。VIP 和积分充值会忽略该字段。
|