78 lines
1.8 KiB
Markdown
78 lines
1.8 KiB
Markdown
# gen2d API 设计
|
||
|
||
所有接口统一前缀 `/api/v1/`，统一响应格式：
|
||
|
||
```json
|
||
{ "code": 0, "message": "ok", "data": {} }
|
||
```
|
||
|
||
## 状态说明
|
||
|
||
- [x] 已完成
|
||
- [ ] 规划中
|
||
|
||
---
|
||
|
||
## 基础设施
|
||
|
||
| 状态 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| [x] | GET | `/api/v1/health` | 健康检查 |
|
||
|
||
## 素材生成
|
||
|
||
| 状态 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| [ ] | POST | `/api/v1/generate` | 提交生成任务，返回 jobId |
|
||
| [ ] | GET | `/api/v1/generate/:jobId` | 查询任务状态与进度 |
|
||
| [ ] | GET | `/api/v1/generate/:jobId/result` | 获取生成结果（素材 URL + 元数据） |
|
||
| [ ] | WS | `/api/v1/generate/:jobId/ws` | WebSocket 实时进度推送 |
|
||
|
||
请求体示例 (POST /api/v1/generate)：
|
||
|
||
```json
|
||
{
|
||
"prompt": "一个拿剑的小人",
|
||
"assetType": "sprite",
|
||
"taskStyle": {
|
||
"scene": "dungeon",
|
||
"mood": "dark"
|
||
},
|
||
"params": {
|
||
"resolution": 64,
|
||
"frames": { "directions": 8, "framesPerDirection": 4 },
|
||
"format": "spritesheet"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `prompt`：用户原始文本，后端 PromptBuilder 负责三段式重写
|
||
- `taskStyle`：可选，任务级别风格覆盖（同名键覆盖工程风格）
|
||
|
||
## 工程风格
|
||
|
||
| 状态 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| [ ] | GET | `/api/v1/projects/:projectId/style` | 获取工程风格 |
|
||
| [ ] | PUT | `/api/v1/projects/:projectId/style` | 更新工程风格 |
|
||
|
||
请求体示例 (PUT /api/v1/projects/:projectId/style)：
|
||
|
||
```json
|
||
{
|
||
"kvPairs": {
|
||
"artStyle": "pixel",
|
||
"palette": "warm",
|
||
"lineWeight": "thin",
|
||
"lighting": "bright"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 缓存管理
|
||
|
||
| 状态 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| [ ] | DELETE | `/api/v1/cache/:key` | 清除特定缓存 |
|
||
| [ ] | POST | `/api/v1/cache/clear` | 批量清除缓存 |
|