| 1 | # 生成角色与场景 |
| 2 | |
| 3 | 执行第二阶段：角色和场景设计。 |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## 请求 |
| 8 | |
| 9 | ```bash |
| 10 | curl -X POST "http://localhost:8000/api/project/{session_id}/execute/character_design" \ |
| 11 | -H "Content-Type: application/json" \ |
| 12 | -d '{"session_id": "xxx"}' |
| 13 | ``` |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 停点说明 |
| 18 | |
| 19 | 此阶段有 1 个停点：角色/场景设计完成后需要用户确认。 |
| 20 | |
| 21 | ## 产物结构 |
| 22 | |
| 23 | ```json |
| 24 | { |
| 25 | "characters": [ |
| 26 | { |
| 27 | "id": "char_1", |
| 28 | "name": "角色名", |
| 29 | "description": "角色描述", |
| 30 | "visual_prompt": "视觉提示词", |
| 31 | "selected": "code/result/image/xxx/character_001.png", |
| 32 | "versions": ["code/result/xxx.png"] |
| 33 | } |
| 34 | ], |
| 35 | "settings": [ |
| 36 | { |
| 37 | "id": "set_1", |
| 38 | "name": "场景名", |
| 39 | "description": "场景描述", |
| 40 | "visual_prompt": "视觉提示词", |
| 41 | "selected": "code/result/image/xxx/setting_001.png", |
| 42 | "versions": [...] |
| 43 | } |
| 44 | ] |
| 45 | } |
| 46 | ``` |
| 47 | |
| 48 | ## 实时反馈 |
| 49 | |
| 50 | 在生成过程中，SSE 会发送 `asset_complete` 事件： |
| 51 | |
| 52 | ```json |
| 53 | { |
| 54 | "type": "progress", |
| 55 | "data": { |
| 56 | "asset_complete": { |
| 57 | "type": "characters|settings", |
| 58 | "id": "char_1", |
| 59 | "status": "done", |
| 60 | "selected": "code/result/image/xxx.png", |
| 61 | "versions": [...] |
| 62 | } |
| 63 | } |
| 64 | } |
| 65 | ``` |
| 66 | |
| 67 | 收到此事件后，必须立即下载图片并发送给用户。 |
| 68 | |
| 69 | ## 停点3：角色/场景设计完成，等待用户确认后继续下一阶段 |
| 70 | |
| 71 | **必须向用户发送消息**，展示完整的角色和场景设计： |
| 72 | |
| 73 | 1. **人物图片**：从 `artifact.characters[].selected` 获取每个人物的图片路径 |
| 74 | 2. **场景图片**：从 `artifact.settings[].selected` 获取每个场景的图片路径 |
| 75 | 3. **人物列表**：包含角色名、描述、视觉提示词 |
| 76 | 4. **场景列表**：包含场景名、描述、视觉提示词 |
| 77 | |
| 78 | **发送消息时必须**： |
| 79 | - 根据消息渠道参考 [send_message/feishu.md](../send_message/feishu.md) 或 [send_message/wechat.md](../send_message/wechat.md) 发送图片 |
| 80 | - 每张图片需附带简短说明（角色名/场景名） |
| 81 | - **发送前端 URL**（获取本地 IPv4 地址，构造 `http://{local_ip}:3000/?session={session_id}&stage=character_design`） |
| 82 | - 发送完整列表后，询问用户确认 |
| 83 | |
| 84 | 询问内容示例： |
| 85 | > "角色和场景设计已完成，共生成 X 个人物和 Y 个场景。请确认是否继续进行分镜设计？" |
| 86 | |
| 87 | ## 继续下一阶段 |
| 88 | |
| 89 | 用户确认后调用： |
| 90 | |
| 91 | ```bash |
| 92 | curl -X POST "http://localhost:8000/api/project/{session_id}/continue" |
| 93 | ``` |
| 94 | |
| 95 | --- |
| 96 | |
| 97 | ## 常见问题 |
| 98 | |
| 99 | | 错误 | 原因 | 解决方法 | |
| 100 | |------|------|----------| |
| 101 | | `curl: (7) Failed to connect` | 后端未运行 | 启动后端服务 | |
| 102 | | `asset_complete` 状态为 failed | 图片生成失败 | 检查 API Key 配置，记录失败原因 | |
| 103 | | 图片下载失败 | URL 路径错误 | 确认 path 格式为 `code/result/...` | |
| 104 | | SSE 连接断开 | 网络超时 | 使用轮询 `/api/project/{session_id}/status` 继续 | |
| 105 | | 用户不确认 | 用户想修改角色 | 调用 modify_character 重新生成 | |
| 106 |