104 lines
2.6 KiB
Markdown
104 lines
2.6 KiB
Markdown
# API 设计文档
|
||
所有接口前缀为 `/api/v1`，返回 JSON 格式数据。认证暂未启用（单用户环境）。
|
||
## 1. AI 模型管理 (`/models`)
|
||
### 1.1 创建模型
|
||
`POST /models`
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"name": "GPT-4",
|
||
"provider": "openai",
|
||
"endpoint": "https://api.openai.com/v1/chat/completions",
|
||
"api_key": "sk-...",
|
||
"extra_params": {"max_tokens": 1000, "temperature": 0.7},
|
||
"is_enabled": true,
|
||
"remark": "主模型"
|
||
}
|
||
```
|
||
**响应**：返回创建的模型对象（API Key 已加密）。
|
||
### 1.2 获取模型列表
|
||
`GET /models?enabled=true&page=1&limit=20`
|
||
**响应**：分页列表。
|
||
### 1.3 获取模型详情
|
||
`GET /models/{id}`
|
||
### 1.4 更新模型
|
||
`PUT /models/{id}`（字段同创建）
|
||
### 1.5 删除模型
|
||
`DELETE /models/{id}`
|
||
### 1.6 启用/禁用
|
||
`PATCH /models/{id}/toggle`
|
||
请求体`{"is_enabled": false}`
|
||
## 2. 模板管理 (`/templates`)
|
||
### 2.1 上传模板
|
||
`POST /templates` (multipart/form-data)
|
||
字段`file` (.docx), `name` (可选)
|
||
**响应**：模板对象（含生成的 HTML 内容）。
|
||
### 2.2 获取模板列表
|
||
`GET /templates` (分页)
|
||
### 2.3 获取模板 HTML 内容
|
||
`GET /templates/{id}/html`
|
||
返回`{"html_content": "<html>..."}`
|
||
### 2.4 更新模板 HTML（编辑后保存）
|
||
`PUT /templates/{id}/html`
|
||
请求体`{"html_content": "<html>..."}`
|
||
后端将同步更新对应的 .docx 文件。
|
||
### 2.5 下载最终文档
|
||
`GET /templates/{id}/download`
|
||
返回文件流（.docx）。
|
||
## 3. 生成点管理 (`/generation-points`)
|
||
### 3.1 创建生成点
|
||
`POST /generation-points`
|
||
```json
|
||
{
|
||
"template_id": "uuid",
|
||
"position": {"start": 100, "end": 200},
|
||
"prompt": "请根据参考文件生成一段总结",
|
||
"model_id": "uuid (可选)",
|
||
"ref_file": "file (multipart, 可选)"
|
||
}
|
||
```
|
||
**响应**：生成点对象。
|
||
### 3.2 获取模板的所有生成点
|
||
`GET /generation-points?template_id={id}`
|
||
### 3.3 更新生成点
|
||
`PUT /generation-points/{id}`（字段同创建）
|
||
### 3.4 删除生成点
|
||
`DELETE /generation-points/{id}`
|
||
## 4. 生成任务 (`/tasks`)
|
||
### 4.1 触发生成任务
|
||
`POST /templates/{template_id}/generate`
|
||
**响应**：
|
||
```json
|
||
{
|
||
"task_id": "uuid",
|
||
"status": "pending"
|
||
}
|
||
```
|
||
### 4.2 查询任务状态
|
||
`GET /tasks/{task_id}`
|
||
**响应**：
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"status": "done",
|
||
"result_file_path": "/path/to/result.docx",
|
||
"error_msg": null,
|
||
"created_at": "...",
|
||
"finished_at": "..."
|
||
}
|
||
```
|
||
### 4.3 下载生成结果
|
||
`GET /tasks/{task_id}/download`
|
||
返回 .docx 文件流。
|
||
## 错误码规范
|
||
- `200`: 成功
|
||
- `400`: 请求参数错误
|
||
- `404`: 资源不存在
|
||
- `500`: 服务器内部错误
|
||
错误响应格式：
|
||
```json
|
||
{
|
||
"detail": "错误描述"
|
||
}
|
||
```
|