| 1 | # 生成参考图 |
| 2 | |
| 3 | 执行第四阶段：为每个分镜生成参考图。 |
| 4 | |
| 5 | ## 请求 |
| 6 | |
| 7 | ```bash |
| 8 | curl -X POST "http://localhost:8000/api/project/{session_id}/execute/reference_generation" \ |
| 9 | -H "Content-Type: application/json" \ |
| 10 | -d '{"session_id": "xxx"}' |
| 11 | ``` |
| 12 | |
| 13 | ## 停点说明 |
| 14 | |
| 15 | 此阶段有 1 个停点：参考图生成完成后需要用户确认。 |
| 16 | |
| 17 | ## 产物结构 |
| 18 | |
| 19 | ```json |
| 20 | { |
| 21 | "scenes": [ |
| 22 | { |
| 23 | "id": "1-1", |
| 24 | "description": "视觉提示词", |
| 25 | "selected": "code/result/image/xxx/shot_001.png", |
| 26 | "versions": ["...", "..."], |
| 27 | "status": "done" |
| 28 | } |
| 29 | ] |
| 30 | } |
| 31 | ``` |
| 32 | |
| 33 | > ⚠️ **注意**：由于系统会对生成的参考图进行质量评估（VLM 评分），质量不合格的图会自动触发重新生成。因此，**参考图生成的总次数通常会大于分镜片段的数量**。在监听 SSE 进度时，请以最终 `status: "done"` 的 `asset_complete` 事件为准。 |
| 34 | |
| 35 | ## 实时反馈 |
| 36 | |
| 37 | 在生成过程中，SSE 会发送 `asset_complete` 事件： |
| 38 | |
| 39 | ```json |
| 40 | { |
| 41 | "type": "progress", |
| 42 | "data": { |
| 43 | "asset_complete": { |
| 44 | "type": "images", |
| 45 | "id": "1-1", |
| 46 | "status": "done", |
| 47 | "selected": "code/result/image/xxx.png", |
| 48 | "versions": [...] |
| 49 | } |
| 50 | } |
| 51 | } |
| 52 | ``` |
| 53 | |
| 54 | 收到此事件后，必须立即下载图片并发送给用户。 |
| 55 | |
| 56 | ## 停点5：参考图生成完成，等待用户确认后继续下一阶段 |
| 57 | |
| 58 | **必须向用户发送消息**，展示每个分镜的参考图： |
| 59 | |
| 60 | 从 `artifact.scenes[].selected` 获取每个分镜的参考图路径。 |
| 61 | |
| 62 | **发送消息时必须**： |
| 63 | - 参考 [send_message/feishu.md](../send_message/feishu.md) 发送图片给用户 |
| 64 | - 每张参考图需附带分镜编号（如"场景1-分镜1：角色A在咖啡馆"） |
| 65 | - 按分镜 ID 顺序依次发送 |
| 66 | - **发送前端 URL**（获取本地 IPv4 地址，构造 `http://{local_ip}:3000/?session={session_id}&stage=reference_generation`） |
| 67 | - 发送完整列表后，询问用户确认 |
| 68 | |
| 69 | 询问内容示例： |
| 70 | > "参考图生成已完成，共 X 张参考图。请确认是否继续生成视频片段？" |
| 71 | |
| 72 | ## 继续下一阶段 |
| 73 | |
| 74 | 用户确认后调用： |
| 75 | |
| 76 | ```bash |
| 77 | curl -X POST "http://localhost:8000/api/project/{session_id}/continue" |
| 78 | ``` |
| 79 | |
| 80 | ## 常见问题 |
| 81 | |
| 82 | | 错误 | 原因 | 解决方法 | |
| 83 | |------|------|----------| |
| 84 | | `curl: (7) Failed to connect` | 后端未运行 | 启动后端服务 | |
| 85 | | `asset_complete` 状态为 failed | 图片生成失败（超时/限流） | 可在请求中设置 `"enable_concurrency": false` 降低并发重试 | |
| 86 | | 图片下载失败 | URL 路径错误 | 确认 path 格式为 `code/result/...` | |
| 87 | | SSE 连接断开 | 网络超时 | 使用轮询 `/api/project/{session_id}/status` 继续 | |
| 88 | | 用户不确认 | 用户想修改参考图 | 调用 modify_reference 重新生成 | |
| 89 |