gen2d/docs/api.md

gen2d API 设计

所有接口统一前缀 /api/v1/，统一响应格式：

{ "code": 0, "message": "ok", "data": {} }

状态说明

• 已完成
• 规划中

---

基础设施

状态	方法	路径	说明
[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)：

{
  "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)：

{
  "kvPairs": {
    "artStyle": "pixel",
    "palette": "warm",
    "lineWeight": "thin",
    "lighting": "bright"
  }
}

缓存管理

状态	方法	路径	说明
[ ]	DELETE	/api/v1/cache/:key	清除特定缓存
[ ]	POST	/api/v1/cache/clear	批量清除缓存