generate-storyboard

Generate Storyboard Images

Create storyboard images using the Gemini 3 Pro Image API.

Content Mode Support

The system supports two content modes; the generation workflow and aspect ratio are automatically adjusted based on the mode:

Mode	Workflow	Aspect Ratio
Narration + Visuals (Default)	Direct Generation(no multi-panel grid)	9:16 Portrait
Drama Animation	Two-step workflow (multi-panel grid → individual scene images)	16:9 Landscape

The aspect ratio is set via API parameters and is not included in the prompt.

Narration Mode Workflow (narration)

Generate Storyboard Images Directly

No multi-panel preview image step required
Generate individual scene images directly (9:16 Portrait）
Use character_sheet and clue_sheet as reference images to maintain character consistency
Save as storyboards/scene_{segment_id}.png
Update the storyboard_image field in the script
Used as the starting frame for video generation

Data Structure

{
  "generated_assets": {
    "storyboard_image": "storyboards/scene_E1S01.png",
    "video_clip": null,
    "status": "storyboard_ready"
  }
}

Note: narration mode does not use the storyboard_grid field

Drama Animation Mode Workflow (drama)

Step 1: Generate Multi-Panel Storyboard Images

Process scenes in batches (4-6 scenes per batch)
Generate multi-panel preview images to ensure character consistency
Adaptive panel layout:
- 1-4 scenes → 2x2 four-panel grid
- 5-6 scenes → 2x3 six-panel grid
Save as storyboards/grid_{batch_id:03d}.png
Update the storyboard_grid field in the script

Step 2: Generate Individual Scene Images

Use the multi-panel image and character design sheets as references
Generate an independent high-quality storyboard image for each scene
The prompt explicitly indicates which panel in the multi-panel grid is being referenced
Use 16:9 Landscape
Save as storyboards/scene_{scene_id}.png
Update the storyboard_image field in the script

Data Structure

{
  "generated_assets": {
    "storyboard_grid": "storyboards/grid_001.png",
    "storyboard_image": "storyboards/scene_E1S01.png",
    "video_clip": null,
    "status": "storyboard_ready"
  }
}

Command-Line Usage

Narration Mode (Recommended)

# 直接生成所有缺失的分镜图
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

Drama Animation Mode

# 步骤 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

Note: The script automatically detects content_mode; in narration mode, the --grids/--scenes parameter is ignored.

Rate Limiting

To handle API limits, the script has a built-in sliding window rate limiter:

Supports configuring rate limits via environment variables (see CLAUDE.md)
Automatically waits when limits are exceeded
Built-in exponential backoff retry mechanism (maximum 5 retries)

Workflow

Load Project and Script
- If no project name is specified, ask the user
- From projects/{项目名}/scripts/ Load Script
- Confirm that all characters have character_sheet images
Generate Storyboard Images
- Run .claude/skills/generate-storyboard/scripts/generate_storyboard.py
- The script automatically detects content_mode and selects the corresponding workflow
Review checkpoint(drama mode)
- Display each multi-panel storyboard image
- Ask the user whether to approve or regenerate
Update script
- Update storyboard_image path
- In drama mode, additionally update storyboard_grid path
- Update scene status

projects/{项目名}/storyboards/
├── grid_001.png           # 多宫格图（场景 E1S01-E1S06）
├── grid_002.png           # 多宫格图（场景 E1S07-E1S12）
├── scene_E1S01.png        # 单独场景图
├── scene_E1S02.png
└── ...

Multi-panel storyboard prompt template

一张 16:9 横屏的多宫格分镜图，包含 [N] 个连续场景。
采用 [2x2/2x3] 宫格布局，每个格子展示一个场景的关键画面。

宫格1（场景 [scene_id]）：
- 画面描述：[visual.description]
- 镜头构图：[visual.shot_type]
- 人物：[characters_in_scene]
- 动作：[action]

宫格2（场景 [scene_id]）：
...

风格要求：
- 电影分镜图风格，{项目 style}
- 每个宫格有清晰的画面焦点
- 宫格之间用细线分隔

人物必须与提供的参考图完全一致。

Single scene image prompt template

根据提供的多宫格分镜参考图，生成其中 第 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 设定
- 画面构图完整，焦点清晰
- 保持与多宫格参考图中对应格子的风格和构图一致

人物必须与提供的人物参考图完全一致。

The aspect ratio (9:16 or 16:9) is set via API parameters and is not written into the prompt.

Field descriptions

Field	Source	Description
description	visual.description	Subject and environment description
shot_type	visual.shot_type	Shot composition type
camera_movement	visual.camera_movement	Camera movement method (the image shows the starting state)
lighting	visual.lighting	Lighting conditions
mood	visual.mood	Image atmosphere and color tone
action	scene.action	Character action description

Character consistency

Key: Always pass in character reference images to maintain consistency. The aspect ratio is automatically selected based on the content mode.

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

Pre-generation check

Confirm before generating storyboards:

All characters have approved character_sheet images
Scene visual descriptions are complete
Character actions have been specified

Quality checklist

Multi-panel storyboard image review

Characters in each panel match the reference images
Panel layout is clear and scenes are coherent
Overall style is unified

Single scene image review

Composition matches the corresponding panel in the multi-panel storyboard
Image quality is suitable as a video starting frame
Lighting and atmosphere are correct
The scene accurately conveys the intended action

Error handling

A single scene failure does not affect the batch: Log the failed scene and continue to the next one
Failure summary report: After generation ends, list all failed scenes and reasons
Incremental generation: Detect existing scene images and skip duplicate generation
Retry support: Use --scenes --scene-ids E1S01 to regenerate failed scenes

About this skill

Content Mode Support

Narration Mode Workflow (narration)

Generate Storyboard Images Directly

Data Structure

Drama Animation Mode Workflow (drama)

Step 1: Generate Multi-Panel Storyboard Images

Step 2: Generate Individual Scene Images

Data Structure

Command-Line Usage

Narration Mode (Recommended)

Drama Animation Mode

Rate Limiting

Workflow

Multi-panel storyboard prompt template

Single scene image prompt template

Field descriptions

Character consistency

Pre-generation check

Quality checklist

Multi-panel storyboard image review

Single scene image review

Error handling