| 1 | # MovieAssistant API 文档 |
| 2 | |
| 3 | ## 概述 |
| 4 | |
| 5 | MovieAssistant 是一个 AI 视频生成系统，提供 REST API 供外部调用。API 与前端共享同一个历史数据库，支持在 API 和前端之间无缝切换。 |
| 6 | |
| 7 | **基础 URL**: `http://localhost:8000` |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## 认证 |
| 12 | |
| 13 | 当前版本无需认证，所有接口均可公开访问。 |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 可用阶段 |
| 18 | |
| 19 | | 阶段 ID | 名称 | 说明 | |
| 20 | |---------|------|------| |
| 21 | | `script_generation` | 剧本生成 | 将灵感转化为结构化剧本 | |
| 22 | | `character_design` | 角色/场景设计 | 生成角色设计图和场景背景 | |
| 23 | | `storyboard` | 分镜设计 | 设计镜头语言和分镜脚本 | |
| 24 | | `reference_generation` | 参考图生成 | 生成高精度参考图 | |
| 25 | | `video_generation` | 视频生成 | 将参考图/分镜图生成视频 | |
| 26 | | `post_production` | 后期剪辑 | 拼接视频片段为最终成片 | |
| 27 | |
| 28 | --- |
| 29 | |
| 30 | ## API 接口列表 |
| 31 | |
| 32 | ### 1. 创建项目 |
| 33 | |
| 34 | 创建一个新的视频生成项目。 |
| 35 | |
| 36 | **接口**: `POST /api/project/start` |
| 37 | |
| 38 | **请求体**: |
| 39 | ```json |
| 40 | { |
| 41 | "idea": "故事线描述", |
| 42 | "style": "anime", |
| 43 | "episodes": 4, |
| 44 | "llm_model": "deepseek-v3.2", |
| 45 | "vlm_model": "qwen3.5-plus", |
| 46 | "image_t2i_model": "doubao-seedream-5-0-260128", |
| 47 | "image_it2i_model": "doubao-seedream-5-0-260128", |
| 48 | "video_model": "wan2.7-i2v", |
| 49 | "enable_concurrency": true |
| 50 | } |
| 51 | ``` |
| 52 | |
| 53 | **参数说明**: |
| 54 | | 参数 | 类型 | 必填 | 说明 | 默认值 | |
| 55 | |------|------|------|------|--------| |
| 56 | | idea | string | 是 | 故事线描述 | - | |
| 57 | | style | string | 否 | 视频风格 | anime | |
| 58 | | episodes | int | 否 | 生成的剧集数量 | 4 | |
| 59 | | llm_model | string | 是 | LLM 模型；前端从 `backend/config.yaml` 读取默认值并传递 | - | |
| 60 | | vlm_model | string | 是 | VLM 评估模型；前端从 `backend/config.yaml` 读取默认值并传递 | - | |
| 61 | | image_t2i_model | string | 是 | 文生图模型；前端从 `backend/config.yaml` 读取默认值并传递 | - | |
| 62 | | image_it2i_model | string | 是 | 图生图模型；前端从 `backend/config.yaml` 读取默认值并传递 | - | |
| 63 | | video_model | string | 是 | 视频模型；前端从 `backend/config.yaml` 读取默认值并传递 | - | |
| 64 | | enable_concurrency | bool | 否 | 开启并发生成（可同时生成多张图片/视频） | true | |
| 65 | |
| 66 | **响应示例**: |
| 67 | ```json |
| 68 | { |
| 69 | "session_id": "1773208355389", |
| 70 | "status": "stage_completed", |
| 71 | "params": { |
| 72 | "idea": "故事线描述", |
| 73 | "style": "anime", |
| 74 | "llm_model": "deepseek-v3.2", |
| 75 | "vlm_model": "qwen3.5-plus", |
| 76 | "episodes": 4 |
| 77 | } |
| 78 | } |
| 79 | ``` |
| 80 | |
| 81 | --- |
| 82 | |
| 83 | ### 2. 执行阶段 |
| 84 | |
| 85 | 执行指定的生成阶段。 |
| 86 | |
| 87 | **接口**: `POST /api/project/{session_id}/execute/{stage}` |
| 88 | |
| 89 | **路径参数**: |
| 90 | - `session_id`: 项目会话 ID |
| 91 | - `stage`: 阶段 ID（见上表） |
| 92 | |
| 93 | **请求体**: |
| 94 | ```json |
| 95 | { |
| 96 | "style": "anime" |
| 97 | } |
| 98 | ``` |
| 99 | |
| 100 | > 请求体参数与创建项目相同（可选），会覆盖项目中已有的对应参数。 |
| 101 | |
| 102 | **响应**: SSE 流式返回，包含以下事件类型： |
| 103 | - `progress`: 进度更新 |
| 104 | - `stage_complete`: 阶段完成 |
| 105 | - `error`: 执行错误 |
| 106 | |
| 107 | **示例 - 进度事件**: |
| 108 | ```json |
| 109 | { |
| 110 | "type": "progress", |
| 111 | "message": "剧本生成: 正在生成...", |
| 112 | "phase": "剧本生成", |
| 113 | "step_desc": "正在生成...", |
| 114 | "percent": 50 |
| 115 | } |
| 116 | ``` |
| 117 | |
| 118 | **示例 - 阶段完成事件**: |
| 119 | ```json |
| 120 | { |
| 121 | "type": "stage_complete", |
| 122 | "stage": "script_generation", |
| 123 | "status": "stage_completed", |
| 124 | "requires_intervention": false |
| 125 | } |
| 126 | ``` |
| 127 | |
| 128 | --- |
| 129 | |
| 130 | ### 3. 获取项目状态 |
| 131 | |
| 132 | 获取项目的当前状态。 |
| 133 | |
| 134 | **接口**: `GET /api/project/{session_id}/status` |
| 135 | |
| 136 | **响应示例**: |
| 137 | ```json |
| 138 | { |
| 139 | "session_id": "1773208355389", |
| 140 | "current_stage": "script_generation", |
| 141 | "status": "running", |
| 142 | "error": null, |
| 143 | "stages_completed": [], |
| 144 | "artifacts": {}, |
| 145 | "meta": { |
| 146 | "idea": "故事线描述", |
| 147 | "style": "anime" |
| 148 | }, |
| 149 | "updated_at": 1773208355389 |
| 150 | } |
| 151 | ``` |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ### 4. 获取阶段产物 |
| 156 | |
| 157 | 获取指定阶段的产物数据。 |
| 158 | |
| 159 | **接口**: `GET /api/project/{session_id}/artifact/{stage}` |
| 160 | |
| 161 | **响应示例** (剧本生成阶段): |
| 162 | ```json |
| 163 | { |
| 164 | "stage": "script_generation", |
| 165 | "artifact": { |
| 166 | "title": "剧本名称", |
| 167 | "logline": "...", |
| 168 | "characters": [...], |
| 169 | "settings": [...], |
| 170 | "episodes": [...] |
| 171 | } |
| 172 | } |
| 173 | ``` |
| 174 | |
| 175 | --- |
| 176 | |
| 177 | ### 5. 更新阶段产物 |
| 178 | |
| 179 | 更新指定阶段的产物数据（如用户修改提示词、选择版本）。 |
| 180 | |
| 181 | **接口**: `PATCH /api/project/{session_id}/artifact/{stage}` |
| 182 | |
| 183 | 请求体格式**因阶段而异**： |
| 184 | |
| 185 | #### storyboard — 修改分集/片段/镜头 |
| 186 | ```json |
| 187 | { |
| 188 | "episodes": [ |
| 189 | { |
| 190 | "episode_number": 1, |
| 191 | "segments": [ |
| 192 | { |
| 193 | "segment_id": "seg_01_01", |
| 194 | "total_duration": 10, |
| 195 | "visual_prompt": "新视觉提示词", |
| 196 | "video_prompt": "新视频提示词", |
| 197 | "shots": [] |
| 198 | } |
| 199 | ] |
| 200 | } |
| 201 | ] |
| 202 | } |
| 203 | ``` |
| 204 | |
| 205 | #### reference_generation — 修改视觉提示词 |
| 206 | ```json |
| 207 | { |
| 208 | "segments": [ |
| 209 | {"segment_id": "seg_01_01", "visual_prompt": "新提示词"} |
| 210 | ] |
| 211 | } |
| 212 | ``` |
| 213 | |
| 214 | #### reference_generation — 选择参考图版本 |
| 215 | ```json |
| 216 | { |
| 217 | "seg_01_01": "code/result/image/xxx/seg_01_01_v2.jpg" |
| 218 | } |
| 219 | ``` |
| 220 | |
| 221 | #### video_generation — 修改片段描述/时长 |
| 222 | ```json |
| 223 | { |
| 224 | "seg_01_01": {"description": "新描述", "duration": 5} |
| 225 | } |
| 226 | ``` |
| 227 | |
| 228 | #### video_generation — 选择视频版本 |
| 229 | ```json |
| 230 | { |
| 231 | "seg_01_01": "code/result/video/xxx/seg_01_01_v2.mp4" |
| 232 | } |
| 233 | ``` |
| 234 | |
| 235 | **响应**: `{"status": "ok"}` |
| 236 | |
| 237 | --- |
| 238 | |
| 239 | ### 6. 干预阶段 |
| 240 | |
| 241 | 对已完成的阶段进行修改并重新执行（重新生成部分产物）。 |
| 242 | |
| 243 | **接口**: `POST /api/project/{session_id}/intervene` |
| 244 | |
| 245 | **请求体**: |
| 246 | ```json |
| 247 | { |
| 248 | "stage": "reference_generation", |
| 249 | "modifications": { |
| 250 | "regenerate_scenes": ["shot_001_01", "shot_001_02"] |
| 251 | } |
| 252 | } |
| 253 | ``` |
| 254 | |
| 255 | - `stage`：要干预的阶段 |
| 256 | - `modifications`：修改内容，目前支持 `regenerate_scenes`（要重新生成的镜头 ID 列表） |
| 257 | |
| 258 | **响应**: SSE 流式返回，包含以下事件类型： |
| 259 | - `progress`: 进度更新 |
| 260 | - `stage_complete`: 阶段完成 |
| 261 | - `error`: 执行错误 |
| 262 | |
| 263 | --- |
| 264 | |
| 265 | ### 7. 确认并继续 |
| 266 | |
| 267 | 确认当前阶段的修改，进入下一阶段。 |
| 268 | |
| 269 | **接口**: `POST /api/project/{session_id}/continue` |
| 270 | |
| 271 | **响应示例**: |
| 272 | ```json |
| 273 | { |
| 274 | "status": "ready", |
| 275 | "next_stage": "character_design" |
| 276 | } |
| 277 | ``` |
| 278 | |
| 279 | --- |
| 280 | |
| 281 | ### 8. 停止执行 |
| 282 | |
| 283 | 停止当前正在执行的阶段。 |
| 284 | |
| 285 | **接口**: `POST /api/project/{session_id}/stop` |
| 286 | |
| 287 | **响应示例**: |
| 288 | ```json |
| 289 | { |
| 290 | "status": "stopped" |
| 291 | } |
| 292 | ``` |
| 293 | |
| 294 | --- |
| 295 | |
| 296 | ### 9. 获取会话列表 |
| 297 | |
| 298 | 获取所有历史项目列表。 |
| 299 | |
| 300 | **接口**: `GET /api/sessions` |
| 301 | |
| 302 | **响应示例**: |
| 303 | ```json |
| 304 | { |
| 305 | "sessions": [ |
| 306 | { |
| 307 | "id": "1773208355389", |
| 308 | "idea": "故事线", |
| 309 | "style": "anime", |
| 310 | "date": 1773208355389, |
| 311 | "stages": ["script_generation", "character_design"] |
| 312 | } |
| 313 | ] |
| 314 | } |
| 315 | ``` |
| 316 | |
| 317 | --- |
| 318 | |
| 319 | ### 10. 获取阶段列表 |
| 320 | |
| 321 | 获取所有可用阶段列表。 |
| 322 | |
| 323 | **接口**: `GET /api/stages` |
| 324 | |
| 325 | **响应示例**: |
| 326 | ```json |
| 327 | { |
| 328 | "stages": [ |
| 329 | {"id": "script_generation", "name": "剧本生成", "order": 1, "description": "将灵感转化为结构化剧本"}, |
| 330 | {"id": "character_design", "name": "角色/场景设计", "order": 2}, |
| 331 | {"id": "storyboard", "name": "分镜设计", "order": 3}, |
| 332 | {"id": "reference_generation", "name": "参考图生成", "order": 4}, |
| 333 | {"id": "video_generation", "name": "视频生成", "order": 5}, |
| 334 | {"id": "post_production", "name": "后期剪辑", "order": 6} |
| 335 | ] |
| 336 | } |
| 337 | ``` |
| 338 | |
| 339 | --- |
| 340 | |
| 341 | ## 调用示例 |
| 342 | |
| 343 | ### 完整流程示例 |
| 344 | |
| 345 | ```bash |
| 346 | # 1. 创建项目 |
| 347 | SESSION_ID=$(curl -s -X POST http://localhost:8000/api/project/start \ |
| 348 | -H "Content-Type: application/json" \ |
| 349 | -d '{ |
| 350 | "idea": "失忆女刺客刺杀目标时恢复记忆,与爱人联手复仇师兄", |
| 351 | "style": "anime" |
| 352 | }' | jq -r '.session_id') |
| 353 | |
| 354 | echo "Session ID: $SESSION_ID" |
| 355 | |
| 356 | # 2. 执行第一阶段（剧本生成）- 监听 SSE |
| 357 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/script_generation" \ |
| 358 | -H "Content-Type: application/json" \ |
| 359 | -d '{"style": "anime"}' |
| 360 | |
| 361 | # 3. 获取剧本产物 |
| 362 | curl -s "http://localhost:8000/api/project/${SESSION_ID}/artifact/script_generation" |
| 363 | |
| 364 | # 4. 确认并继续到下一阶段 |
| 365 | curl -s -X POST "http://localhost:8000/api/project/${SESSION_ID}/continue" |
| 366 | |
| 367 | # 5. 执行第二阶段（角色设计） |
| 368 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/character_design" \ |
| 369 | -H "Content-Type: application/json" \ |
| 370 | -d '{"style": "anime"}' |
| 371 | |
| 372 | # 6. 确认并继续 |
| 373 | curl -s -X POST "http://localhost:8000/api/project/${SESSION_ID}/continue" |
| 374 | |
| 375 | # 7. 执行第三阶段（分镜设计） |
| 376 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/storyboard" \ |
| 377 | -H "Content-Type: application/json" \ |
| 378 | -d '{"style": "anime"}' |
| 379 | |
| 380 | # 8. 确认并继续 |
| 381 | curl -s -X POST "http://localhost:8000/api/project/${SESSION_ID}/continue" |
| 382 | |
| 383 | # 9. 执行第四阶段（参考图生成） |
| 384 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/reference_generation" \ |
| 385 | -H "Content-Type: application/json" \ |
| 386 | -d '{"style": "anime"}' |
| 387 | |
| 388 | # 10. 确认并继续 |
| 389 | curl -s -X POST "http://localhost:8000/api/project/${SESSION_ID}/continue" |
| 390 | |
| 391 | # 11. 执行第五阶段（视频生成） |
| 392 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/video_generation" \ |
| 393 | -H "Content-Type: application/json" \ |
| 394 | -d '{"style": "anime"}' |
| 395 | |
| 396 | # 12. 确认并继续 |
| 397 | curl -s -X POST "http://localhost:8000/api/project/${SESSION_ID}/continue" |
| 398 | |
| 399 | # 13. 执行第六阶段（后期剪辑） |
| 400 | curl -X POST "http://localhost:8000/api/project/${SESSION_ID}/execute/post_production" \ |
| 401 | -H "Content-Type: application/json" \ |
| 402 | -d '{"style": "anime"}' |
| 403 | ``` |
| 404 | |
| 405 | ### 使用 jq 简化 |
| 406 | |
| 407 | ```bash |
| 408 | # 创建项目并提取 session_id |
| 409 | SESSION_ID=$(curl -s -X POST http://localhost:8000/api/project/start \ |
| 410 | -H "Content-Type: application/json" \ |
| 411 | -d '{"idea": "故事线", "style": "anime"}' | python3 -c "import json,sys; print(json.load(sys.stdin)['session_id'])") |
| 412 | |
| 413 | # 查看项目状态 |
| 414 | curl -s "http://localhost:8000/api/project/${SESSION_ID}/status" | python3 -m json.tool |
| 415 | ``` |
| 416 | |
| 417 | --- |
| 418 | |
| 419 | ## 错误处理 |
| 420 | |
| 421 | ### HTTP 状态码 |
| 422 | |
| 423 | | 状态码 | 说明 | |
| 424 | |--------|------| |
| 425 | | 200 | 请求成功 | |
| 426 | | 400 | 请求参数错误 | |
| 427 | | 404 | 资源不存在 | |
| 428 | | 500 | 服务器内部错误 | |
| 429 | |
| 430 | ### 错误响应格式 |
| 431 | |
| 432 | ```json |
| 433 | { |
| 434 | "detail": "错误描述" |
| 435 | } |
| 436 | ``` |
| 437 | |
| 438 | ### 常见错误 |
| 439 | |
| 440 | | 错误 | 说明 | |
| 441 | |------|------| |
| 442 | | Session not found | 指定的 session_id 不存在 | |
| 443 | | Artifact for stage 'xxx' not found | 指定阶段的产物不存在 | |
| 444 | | 阶段执行失败 | 阶段执行过程中发生错误 | |
| 445 | |
| 446 | --- |
| 447 | |
| 448 | ## 前端与 API 共享 |
| 449 | |
| 450 | API 和前端共享同一个 session 存储： |
| 451 | - Session 文件位置: `backend/code/data/sessions/{session_id}.json` |
| 452 | - 产物位置: `backend/code/result/` |
| 453 | |
| 454 | 这意味着： |
| 455 | 1. API 创建的项目可以在前端查看和继续 |
| 456 | 2. 前端创建的项目可以继续使用 API 操作 |
| 457 | 3. 两种方式可以随时切换 |
| 458 |