漫剧生成 Skill
核心原则
每个阶段完成后必须暂停，展示产物，等用户确认或修改后再进入下一阶段。
禁止一口气跑完所有阶段——用户需要在每个关卡看到结果并决定是否调整。
[阶段1] 剧本 ──→ ⏸ 用户确认
↓
[阶段2] 分镜表 ──→ ⏸ 用户确认
↓
[阶段3] 人设 + 画风 ──→ ⏸ 用户确认
↓
[阶段4] 分镜图生成（call_image_api.py）──→ ⏸ 用户确认图像质量
↓
[阶段5] 视频生成（call_video_api.py）
技术栈
| 用途 | 模型 | SDK 调用方式 |
|---|
| 图像（人设图 + 分镜图） | doubao-seedream-5-0-260128 | client.images.generate |
| 视频（图生视频） | doubao-seedance-1-0-lite-i2v-250428（调试）<br>doubao-seedance-1-0-pro-250528（正式） | client.content_generation.tasks.create |
只需一个 Key：ARK_API_KEY（方舟平台统一鉴权）
export ARK_API_KEY="your_key_here"
# 或在脚本顶部直接填写 ARK_API_KEY = "..."
阶段1：剧本创作
参考： references/script-template.md
- 若用户提供完整剧本 → 跳过，直接进阶段2
- 若用户提供创意/想法 → 输出：世界观、角色清单、三幕大纲、分场景剧本（含台词/动作/情绪）
保存：output/[剧名]/script.md
⏸ 检查点：展示剧本，询问是否调整，确认后进阶段2。
阶段2：分镜设计
参考： references/storyboard-guide.md
同时输出两个文件：
storyboard.md（供人阅读）
完整分镜表格，见 storyboard-guide.md
storyboard.json（供脚本调用）
{
"title": "剧名",
"art_style_prefix": "",
"shots": [
{
"shot_id": "S01_01",
"duration": 4,
"description_cn": "中文画面说明",
"image_prompt": "静态画面的英文描述，不含运动",
"video_prompt": "运动方式描述，如 character walking slowly forward",
"characters": ["CHAR_001"],
"dialogue": "台词/音效",
"reference_image": null
}
]
}
image_prompt vs video_prompt 分工：
image_prompt：描述画面构成（景别、角色、场景、光线），用于生成静态分镜图video_prompt：只描述运动（镜头运动 + 角色动作），图生视频时用
⏸ 检查点：展示分镜表，提示用户此处调整最省钱，确认后进阶段3。
阶段3：人设 + 画风设定
参考： references/character-guide.md
3A. 输出角色人设卡：characters/CHAR_001.md
人设卡必须包含可直接用于 Prompt 的精确外貌描述，以及完整的图像生成 Prompt。示例结构：
## CHAR_001 — [角色名]
年龄/性别/身份/性格关键词
### 外貌
发型发色 / 眼睛 / 体型 / 标志性特征（疤痕/纹路/配件）
### 服装（日常 / 战斗）
### 图像生成 Prompt（英文，完整可直接使用）
17-year-old teenage boy, [detailed appearance], [clothing],
full body front view, white background,
anime style, cel shading, shonen manga, high quality, masterpiece, sharp focus
ref_image_path:
3B. 确定画风，填入 storyboard.json
"art_style_prefix": "anime style, shonen manga, cel shading, vibrant colors, high quality, masterpiece"
3C. ⚡ 关键步骤：更新脚本的 CHARACTER_PROMPTS
将角色 Prompt 填入 call_image_api.py 顶部的字典，每次有新角色都要更新：
CHARACTER_PROMPTS = {
"CHAR_001": "17-year-old teenage boy, black short hair, ..., full body front view, white background, anime style, ...",
"CHAR_002": "...",
}
⏸ 检查点：展示所有人设卡 + 画风设定，确认 Prompt 准确描述了目标形象后进阶段4（开始消耗 API 额度）。
阶段4：分镜图生成
脚本： scripts/call_image_api.py
API： 方舟 doubao-seedream-5-0-260128，size=2K
运行命令
# Step 1：生成角色人设参考图
python call_image_api.py characters \
--output output/[剧名]/characters/images/
# Step 2：生成分镜图（读取 storyboard.json 的 art_style_prefix + image_prompt）
python call_image_api.py storyboard \
--input output/[剧名]/storyboard.json \
--output output/[剧名]/storyboard/frames/
脚本完成后自动将帧图路径写回 storyboard.json 的 reference_image 字段。
⏸ 检查点：引导用户打开 storyboard/frames/ 查看图像，重点检查：
- 角色外貌是否符合人设
- 场景氛围/构图是否正确
- 记录需要重生成的 shot_id（可单独重跑）
确认后进阶段5。
阶段5：视频生成
脚本： scripts/call_video_api.py
API： 方舟 doubao-seedance-1-0-lite-i2v-250428（lite，调试）
前置条件：storyboard.json 中所有 shot 的 reference_image 已填写。
运行命令
python call_video_api.py batch \
--input output/[剧名]/storyboard.json \
--output output/[剧名]/videos/
# 如图片目录非默认，加 --frames-dir
python call_video_api.py batch \
--input output/[剧名]/storyboard.json \
--output output/[剧名]/videos/ \
--frames-dir output/[剧名]/storyboard/frames/
脚本工作流：提交任务 → 每8s轮询 → 成功后下载 .mp4 → 更新 generation_log.json。
lite vs pro 切换
# call_video_api.py 顶部修改这一行
ARK_VIDEO_MODEL = "doubao-seedance-1-0-lite-i2v-250428" # 调试
ARK_VIDEO_MODEL = "doubao-seedance-1-0-pro-250528" # 正式出片
输出文件结构
output/[剧名]/
├── script.md
├── storyboard.md
├── storyboard.json ← 核心，贯穿阶段2-5
├── art_style.md
├── characters/
│ ├── CHAR_001.md
│ └── images/
│ └── CHAR_001_front.png
├── storyboard/
│ └── frames/
│ ├── S01_01.png ← 阶段4产物 = 阶段5首帧
│ └── ...
├── videos/
│ └── S01_01.mp4
└── generation_log.json
常见问题快查
| 问题 | 解决方式 |
|---|
❌ 未配置 ARK_API_KEY | 脚本顶部填写，或 export ARK_API_KEY=xxx |
❌ 找不到参考图 | 先完成阶段4生成分镜图；或用 --frames-dir 手动指定 |
| 视频人物外貌与分镜图不符 | video_prompt 只描述动作，不重复角色外貌 |
| 图像风格不统一 | 检查 storyboard.json 的 art_style_prefix 是否已填写 |
volcengine SDK 未安装 | pip install 'volcengine-python-sdk[ark]' requests |
