# AI 姿势画廊 API：Agent 使用指南

## 连接信息

- Base URL：`https://pose.51proxy.org`
- OpenAPI：`https://pose.51proxy.org/openapi.json`
- 认证：`Authorization: Bearer <API_TOKEN>`
- 数据格式：JSON，UTF-8
- 图片：缩略图为 300×400 JPEG，原图为 900×1200 PNG

除 `/api/health`、本文档、OpenAPI 和登录页外，所有 API 与图片都需要认证。Token 应放在请求头，不要放进 URL、日志、提示词输出或公开文件。

```http
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

## 推荐调用流程

1. 调用 `GET /api/meta`，读取系统、分类、角度以及总量。
2. 调用 `GET /api/poses` 搜索姿势。默认每页 60 条，最大 200 条。
3. 从列表取得 `pose.id`，再调用 `GET /api/pose/{id}` 获取全部角度。
4. 预览使用 `thumb_url`，高分辨率处理使用 `original_url`。图片请求也必须携带 Bearer Token。

## 查询规则

`GET /api/poses` 与 `GET /api/images` 支持相同筛选参数：

| 参数 | 类型 | 说明 |
|---|---|---|
| `system` | string | 系统 slug，例如 `full-sexy`、`full-standard`、`upper-body`、`pair` |
| `category` | string | 分类 ID，必须先从 `/api/meta` 获取 |
| `angle` | string | 存储值：`正面`、`上から`、`下から`、`横`、`斜め` |
| `q` | string | 搜索中文/日文姿势名、姿势编号、ID、分类；最长 120 字符 |
| `page` | integer | 从 1 开始，默认 1 |
| `limit` | integer | 1–200；姿势默认 60，图片默认 80 |

响应中的 `angle` 是稳定筛选值，`angle_zh` 是中文展示值。程序应传递 `angle`，向用户展示 `angle_zh`。

## 端点

### `GET /api/meta`

返回所有系统、分类、角度和总量。Agent 应把它作为发现入口，不要硬编码分类 ID。

### `GET /api/poses`

按姿势聚合返回。每条记录包含中文/日文名称、系统、分类、图片数以及封面图。使用 `has_more` 判断是否继续翻页。

示例：搜索“撩发”，只取上半身姿势。

```bash
curl -H "Authorization: Bearer $POSE_API_TOKEN" \
  "https://pose.51proxy.org/api/poses?system=upper-body&q=%E6%92%A9%E5%8F%91&limit=20"
```

### `GET /api/images`

逐张图片返回，适合构建训练清单、按角度选图或批量预览。响应数量是图片数，不是姿势数。

### `GET /api/pose/{id}`

返回单个姿势与全部可用角度。`id` 必须来自 `/api/poses`，例如 `full-sexy_P001`。

### `GET /thumb/{filename}` 与 `GET /img/{filename}`

分别返回缩略图和原图。推荐先请求缩略图；只有确实需要像素数据时再请求原图。支持 ETag，客户端应复用缓存。

## 错误处理

| 状态码 | 含义 | Agent 行为 |
|---|---|---|
| `400` | 参数或对象键无效 | 修正请求，不要原样重试 |
| `401` | 缺少或无效 Token | 检查 Bearer Token，不要切换成 URL 参数 |
| `404` | 姿势、图片或端点不存在 | 重新从列表发现 ID |
| `413` | 上传对象过大 | 管理端上传需减小文件 |
| `500` | 服务端错误 | 指数退避重试，最多 3 次 |

## Agent 安全约束

- API 是只读内容库；不要调用 `/api/admin/*`，除非操作者明确提供管理任务和上传凭据。
- 不要猜测分类 ID、姿势 ID 或图片文件名。
- 不要并发下载全部原图；先过滤、分页并使用缩略图。
- 不要在回答中泄露 Token。
- 遇到 `401` 时停止并要求操作者提供有效凭据，不要尝试绕过登录。

## 最小 JavaScript 示例

```js
const baseUrl = 'https://pose.51proxy.org';
const headers = { Authorization: `Bearer ${process.env.POSE_API_TOKEN}` };

const response = await fetch(`${baseUrl}/api/poses?q=${encodeURIComponent('侧卧')}&limit=10`, { headers });
if (!response.ok) throw new Error(`Pose API ${response.status}`);
const { poses } = await response.json();

for (const pose of poses) {
  console.log(pose.id, pose.name_zh, new URL(pose.cover.thumb_url, baseUrl).href);
}
```
