// 使用 Gemini 图像 API 生成分镜图。说书模式直接生成分镜图，剧集动画模式使用两步流程。使用场景：(1) 用户运行 /generate-storyboard 命令，(2) 剧本中有场景没有分镜图，(3) 用户想在视频生成前预览场景。
使用 Gemini API 生成 JSON 剧本。使用场景：(1) 用户运行 /generate-script 命令，(2) 已完成 Step 1/2 需要生成最终剧本。读取 step1_segments.md 和 project.json，调用 gemini-3-flash-preview 生成符合 Pydantic 模型的 JSON 剧本。
使用 Gemini 图像生成 API 为视频生成人物设计图。使用场景：(1) 用户需要为项目生成人物参考图，(2) 用户运行 /generate-characters 命令，(3) 剧本中有人物没有 character_sheet 路径。生成一致的人物设计用于分镜和视频生成。
使用 Gemini 图像生成 API 为视频生成线索设计图。使用场景：(1) 用户需要为项目生成线索参考图，(2) 用户运行 /generate-clues 命令，(3) project.json 中有 importance='major' 的线索没有 clue_sheet 路径。生成一致的线索设计用于分镜和视频生成。
使用 Veo 3.1 API 为每个场景独立生成视频片段，以分镜图作为起始帧，然后使用 ffmpeg 拼接。使用场景：(1) 用户运行 /generate-video 命令，(2) 剧本中有场景没有 video_clip 路径，(3) 用户想将分镜图转换为视频。
完整的端到端工作流程，将小说转换为视频。使用场景：(1) 用户运行 /manga-workflow 命令，(2) 用户想开始新的视频项目，(3) 用户想继续现有项目。按顺序编排所有其他 skill，并在每个阶段设置审核检查点。
使用 ffmpeg 进行视频后期处理。使用场景：(1) 用户运行 /compose-video 命令，(2) 需要添加背景音乐、片头片尾，(3) 需要合并多个 episode 的视频。主要用于后期处理，视频连贯性由 generate-video 的连续模式保证。
| name | generate-storyboard |
| description | 使用 Gemini 图像 API 生成分镜图。说书模式直接生成分镜图，剧集动画模式使用两步流程。使用场景：(1) 用户运行 /generate-storyboard 命令，(2) 剧本中有场景没有分镜图，(3) 用户想在视频生成前预览场景。 |
使用 Gemini 3 Pro Image API 创建分镜图。
系统支持两种内容模式，生成流程和画面比例根据模式自动调整：
| 模式 | 流程 | 画面比例 |
|---|---|---|
| 说书+画面（默认） | 直接生成（无多宫格） | 9:16 竖屏 |
| 剧集动画 | 两步流程（多宫格→单独场景图） | 16:9 横屏 |
画面比例通过 API 参数设置，不包含在 prompt 中。
storyboards/scene_{segment_id}.pngstoryboard_image 字段{
"generated_assets": {
"storyboard_image": "storyboards/scene_E1S01.png",
"video_clip": null,
"status": "storyboard_ready"
}
}
注意：narration 模式不使用
storyboard_grid字段
storyboards/grid_{batch_id:03d}.pngstoryboard_grid 字段storyboards/scene_{scene_id}.pngstoryboard_image 字段{
"generated_assets": {
"storyboard_grid": "storyboards/grid_001.png",
"storyboard_image": "storyboards/scene_E1S01.png",
"video_clip": null,
"status": "storyboard_ready"
}
}
# 直接生成所有缺失的分镜图
python .claude/skills/generate-storyboard/scripts/generate_storyboard.py \
my_project script.json
# 为指定片段重新生成
python .claude/skills/generate-storyboard/scripts/generate_storyboard.py \
my_project script.json --segment-ids E1S01 E1S02
# 步骤 1：生成多宫格预览图
python .claude/skills/generate-storyboard/scripts/generate_storyboard.py \
my_project script.json --grids --all
# 步骤 2：生成单独场景图
python .claude/skills/generate-storyboard/scripts/generate_storyboard.py \
my_project script.json --scenes
注意：脚本会自动检测 content_mode，narration 模式下
--grids/--scenes参数会被忽略。
为了应对 API 限制，脚本内置了滑动窗口限流器：
加载项目和剧本
projects/{项目名}/scripts/ 加载剧本character_sheet 图像生成分镜图
.claude/skills/generate-storyboard/scripts/generate_storyboard.py审核检查点（drama 模式）
更新剧本
storyboard_image 路径storyboard_grid 路径projects/{项目名}/storyboards/
├── grid_001.png # 多宫格图（场景 E1S01-E1S06）
├── grid_002.png # 多宫格图（场景 E1S07-E1S12）
├── scene_E1S01.png # 单独场景图
├── scene_E1S02.png
└── ...
一张 16:9 横屏的多宫格分镜图，包含 [N] 个连续场景。
采用 [2x2/2x3] 宫格布局，每个格子展示一个场景的关键画面。
宫格1（场景 [scene_id]）：
- 画面描述：[visual.description]
- 镜头构图：[visual.shot_type]
- 人物：[characters_in_scene]
- 动作：[action]
宫格2（场景 [scene_id]）：
...
风格要求：
- 电影分镜图风格，{项目 style}
- 每个宫格有清晰的画面焦点
- 宫格之间用细线分隔
人物必须与提供的参考图完全一致。
根据提供的多宫格分镜参考图，生成其中 第 X 行第 Y 列（宫格 N）的单独高清场景图。
参考图是一张 [2x2/2x3] 布局的多宫格分镜图，请将该格子的内容单独生成为一张完整的图片。
场景 [scene_id] 的详细要求：
- 画面描述：[visual.description]
- 镜头构图：[visual.shot_type]（wide shot / medium shot / close-up / extreme close-up）
- 镜头运动起点：[visual.camera_movement]
- 光线条件：[visual.lighting]
- 画面氛围：[visual.mood]
- 人物：[characters_in_scene]
- 动作：[action]
风格要求：
- 电影分镜图风格，根据项目 style 设定
- 画面构图完整，焦点清晰
- 保持与多宫格参考图中对应格子的风格和构图一致
人物必须与提供的人物参考图完全一致。
画面比例（9:16 或 16:9）通过 API 参数设置，不写入 prompt。
| 字段 | 来源 | 说明 |
|---|---|---|
| description | visual.description | 主体和环境描述 |
| shot_type | visual.shot_type | 镜头构图类型 |
| camera_movement | visual.camera_movement | 镜头运动方式（图片表现起始状态） |
| lighting | visual.lighting | 光线条件 |
| mood | visual.mood | 画面氛围和色调 |
| action | scene.action | 人物动作描述 |
关键：始终传入人物参考图以保持一致性。画面比例根据内容模式自动选择。
from lib.gemini_client import GeminiClient
client = GeminiClient()
# 多宫格分镜图（始终 16:9）
image = client.generate_image(
prompt=grid_prompt,
reference_images=[
f"projects/{项目名}/characters/{人物名}.png"
for 人物名 in batch_characters
],
aspect_ratio="16:9",
output_path=f"projects/{项目名}/storyboards/grid_{batch_id}.png"
)
# 单独场景图（根据内容模式选择画面比例）
# 说书模式: 9:16, 剧集动画模式: 16:9
storyboard_aspect_ratio = get_aspect_ratio(project_data, 'storyboard')
image = client.generate_image(
prompt=scene_prompt,
reference_images=[
f"projects/{项目名}/storyboards/grid_{batch_id}.png", # 多宫格参考
f"projects/{项目名}/characters/{人物名}.png" # 人物参考
],
aspect_ratio=storyboard_aspect_ratio,
output_path=f"projects/{项目名}/storyboards/scene_{scene_id}.png"
)
生成分镜前确认：
--scenes --scene-ids E1S01 重新生成失败场景