动画视频生成V2

概述

动画视频生成

从提示词、视频脚本或小说文本，一键生成真正的短剧动画视频——角色能动、能转、能互动，不是图片配音拼贴。

核心链路：剧本生成 → AI 视频生成 → TTS 配音 → 片头片尾 → BGM 合成 → 1080P MP4。支持竖屏与横屏双模式，由 --ratio 参数全链路贯通。

前提条件

必需

• Python 3.10+
• FFmpeg（或 imageio-ffmpeg）
• Pillow

AI 视频模式（推荐）

• 即梦 API Key（火山方舟）：环境变量 ARK_API_KEY
• 获取地址：https://console.volcengine.com/ark
• httpx（推荐）或 requests
• scripts/video_api_config.json 已预配端点和模型 ID，通常只需设置环境变量

回退模式（无 API Key 时自动启用）

无需 API Key，但产出的是静态图 + Ken Burns 缩放，不是真正的动画。

设置 API Key：

# Windows (cmd)
set ARK_API_KEY=your-api-key-here

# Windows (PowerShell)
$env:ARK_API_KEY="your-api-key-here"

更新记录

• v2.6（2026-09-24）：修复三处导致渲染中断的缺陷 —— ① 字幕样式键名不匹配（outline_colour 等英式拼写 vs 字典美式键名）使任何画风在字幕阶段必崩 KeyError；② concat 清单写相对路径+反斜杠且用 -safe 1，触发 Unsafe file name 导致合并失败；③ tts_engine.py --health-check / --test 被 --script 必填拦住。详细见 references/update_notes.md。
• v2.5（2026-09-09）：全链路新增横屏输出，--ratio 参数贯通 5 个核心脚本；优先级 CLI > 剧本 JSON > 默认 9:16。
• v2.4：分镜细化字段（action/shot_type/camera/ambient/emotion/duration_seconds）；斜杠多选原型音色映射修复；本地免版权 BGM 曲库索引；10 种可合成音效；真实 xfade 转场（不再插黑帧）；animate_video.py 预览改为默认关闭；新增平台规格与免费素材参考。
• v2.3 及以前：六层级 TTS 回退链、即梦 7 模式、5 种画风。

v2.5 横屏升级的逐文件改动清单与全链路参数传递路径见 references/update_notes.md。

模型矩阵

视频生成模型（Seedance）

图片生成模型（Seedream）

7 种 CLI 模式

ai_video_generator.py 的 7 个子命令，前 6 个是生成模式，第 7 个是批量入口：

1. text2img — 文生图（Seedream）

python scripts/ai_video_generator.py text2img --prompt "夜晚城市天台, 赛博朋克风格" --model seedream-5.0-lite --size 2048x2048

额外参数：--size 图片分辨率、--n 生成数量、--ref-image 参考图（img2img）、--guidance-scale 提示词遵循度 1-10。

2. text2video — 文生视频（Seedance）

python scripts/ai_video_generator.py text2video --prompt "年轻女子在城堡广场上缓缓转身, anime style" --model seedance-2.0 --duration 5 --ratio 9:16

3. img2video — 图生视频（首帧 ± 尾帧）

# 仅首帧
python scripts/ai_video_generator.py img2video --prompt "女子转身, 头发飘动" --image first.png --model seedance-2.0

# 首尾帧模式：首帧定开头，尾帧定结尾，AI 生成中间过渡
python scripts/ai_video_generator.py img2video --prompt "从站立到坐下" --image first.png --last-frame last.png

跨镜头角色一致性靠"上一段尾帧当下一段首帧"实现，见下方视频续写。

4. ref2video — 参考图生视频（≤9 张）

在 prompt 中用 [图1]...[图2]... 指定各图作用。

python scripts/ai_video_generator.py ref2video --prompt "[图1]角色造型 [图2]场景背景, 角色在场景中行走" --ref char.png,bg.png --model seedance-2.0

5. vivid2video — 参考视频复刻（≤3 段）

提取参考视频的运动轨迹/运镜/节奏，应用到新内容上。

python scripts/ai_video_generator.py vivid2video --prompt "赛博朋克城市街道, 相同运镜" --ref-video ref_motion.mp4 --model seedance-2.0

6. multimodal — 多模态参考融合

图片（≤9 张）+ 视频（≤3 段，总 ≤15s）+ 音频（≤3 段，总 ≤15s）+ 文本，全能参考融合。仅 seedance-2.0 / 2.0-fast 支持。

python scripts/ai_video_generator.py multimodal --prompt "[图1]角色 [图2]场景 [视频1]运动参考" --ref char.png,bg.png --ref-video motion.mp4 --ref-audio bgm.mp3 --model seedance-2.0

7. batch — 剧本批量生成

从剧本 JSON 一次性生成全部场景视频，是主流程实际使用的入口。

python scripts/ai_video_generator.py batch --script drama.json

视频续写（video_extend）

这不是独立子命令，而是 seedance-2.0 的能力。用 --return-last-frame 拿到尾帧，作为下一段的首帧：

# 第一段（返回尾帧）
python scripts/ai_video_generator.py img2video --prompt "角色开始行走" --image first.png --return-last-frame --output seg1.mp4

# 第二段（用上一段尾帧作为首帧）
python scripts/ai_video_generator.py img2video --prompt "角色继续行走" --image seg1_lastframe.png --output seg2.mp4

即梦特色参数

三种输入模式

• --duration 单位是分钟（默认 1.5）；--episode 指定集数（默认 1）；--list-genres 列出全部类型模板
• 模式 B 支持 dialogue（对话）/ markdown / novel（小说）/ srt（字幕）/ storyboard（分镜）5 种格式，也可用 auto 检测。各格式输入样例与提示词写法见 references/prompt_engineering_guide.md

完整制作流程

用户输入（提示词/脚本/小说）
    ↓
① 剧本生成（提示词→骨架 / 脚本→解析）
    ↓
② LLM 填充对白、画面描述、旁白
    ↓
③ AI 视频生成 API → 角色动画视频片段（角色能动）
    ├─ text2video / img2video / ref2video / vivid2video / multimodal / batch
    ↓  (未配置 API 时：回退到 ImageGen + Ken Burns 缩放)
④ TTS 配音（六层级回退：火山 → edge-tts → gTTS → pyttsx3 → SAPI5 → 静音占位）
    ↓  (三大服务商独立，微软全线故障时 Google/火山仍可用)
⑤ 片头 + 片尾动画
    ↓
⑥ BGM 混音 + FFmpeg 合成最终 1080P MP4（竖屏 9:16 或 横屏 16:9/4:3）

步骤①：剧本生成

提示词模式：

python scripts/script_generator.py --prompt "霸道总裁爱上的灰姑娘其实隐藏身份" --genre 都市爱情 --duration 2 --output drama.json

--genre 可选：都市爱情 / 古装宫斗 / 悬疑推理 / 校园青春 / 逆袭爽文 / 玄幻修仙

脚本解析模式：

python scripts/script_parser.py --input my_script.txt --format auto --title "我的短剧" --output drama.json

半自动分镜模式（适合宣传片/讲解片，而非剧情短剧）：

# 生成分镜计划（plan 默认横屏 16:9，可用 --ratio 9:16 切竖屏）
python scripts/script_director.py plan --topic "新品发布宣传片" --template promotion --style tech --ratio 16:9 -o project.json

# 导出生成指令
python scripts/script_director.py export --project project.json -o output_dir

plan 额外参数：--script 改用现成脚本、--size 画面尺寸、--scene-duration 单镜时长。

5 种分镜模板：narrative（叙事型）/ promotion（推宣型）/ explainer（讲解型）/ showcase（展示型）/ emotional（情感型）

剧本 JSON 字段定义见 references/short_drama_guide.md。

步骤②：LLM 填充剧本

骨架中的 background_prompt、dialogues、narration 字段由 LLM 补充。

步骤③：AI 视频片段生成

# 生成剧本中所有场景的 AI 视频
python scripts/short_drama_renderer.py --script drama.json --action videos

# 或单独生成一个片段
python scripts/ai_video_generator.py text2video --prompt "年轻女子在城堡广场上缓缓转身, anime style, 9:16 vertical" --model seedance-2.0

提示词构建规则： 背景描述 + 角色描述 + 动作运镜 + 画风后缀，自动拼接。

• 画风：anime / qcomic / realistic / cute / korean_manga
• 运镜：close_up / pan / zoom_in / zoom_out / static / dramatic

API 配置与错误码见 references/ai_video_api.md。

步骤④：TTS 配音

六层级回退链，逐级降级，任一环节失败自动尝试下一层：

情感关键词共 14 个（angry / cheerful / sad / serious / friendly / gentle / narrative / newscast / terrified / excited / whisper / shout / sarcastic / romantic），映射到 10 种底层风格；不适用的风格会就近归并（如 terrified→sad、whisper→gentle）。音色清单见 references/tts_voices.md。

独立运行 TTS（可单独测音色，不必跑全流程）：

# 为剧本生成全部配音
python scripts/tts_engine.py --script drama.json --output-dir .temp/audio

# 仅做预检：检查哪些后端可用，避免渲染中途才发现全线故障
python scripts/tts_engine.py --health-check

# 测试模式：只生成一条，快速试音色
python scripts/tts_engine.py --test

# 指定角色音色映射 / 调整重试次数 / 跳过预检
python scripts/tts_engine.py --script drama.json --voices voices.json --max-retries 5 --no-health-check

角色音色映射由 script_generator.py 的 generate_voice_mapping() 生成，可手工调整后回传 --voices。

步骤⑤⑥：片头片尾 + 合成

# 一键完整渲染（画面比例自动读剧本 JSON，也可用 --ratio 覆盖）
python scripts/short_drama_renderer.py --script drama.json --action all --output 短剧第一集.mp4

# 指定横屏 16:9（覆盖剧本中的比例设置）
python scripts/short_drama_renderer.py --script drama.json --action all --ratio 16:9 --output 短剧第一集.mp4

# 添加 BGM
python scripts/short_drama_renderer.py --script drama.json --action all --bgm bgm.mp3 --output 短剧第一集.mp4

--action 可选：videos（只出视频片段）/ all（全流程）。--model 指定视频模型，--no-fallback 强制不使用 Ken Burns 回退（API 失败即报错）。

可用转场（10 种）： fade_black（黑场）、flash_white（闪白）、crossfade（交叉淡化）、slide_left / slide_right（左右滑）、push_up（上推）、zoom_in（推近）、dissolve（溶解）、dissolve_flash（溶解+闪白，戏剧高潮）、cut（硬切）。

# 查看转场清单及其适用情绪
python scripts/transition_effects.py list

# 生成单个转场素材 / 应用到两段视频之间
python scripts/transition_effects.py generate --type dissolve_flash --duration 0.5 --width 1080 --height 1920 --output tr.mp4
python scripts/transition_effects.py apply --video1 a.mp4 --video2 b.mp4 --type fade_black --output joined.mp4

步骤⑥补充：BGM 曲库与音效

本地免版权曲库： 子目录按情绪分类，或文件名带情绪关键词。

set BGM_LIBRARY_DIR=D:bgm_library

# 扫描曲库建立索引（--dir 可临时覆盖环境变量）
python scripts/bgm_manager.py scan
python scripts/bgm_manager.py scan --dir D:other_library

# 列出支持的情绪分类
python scripts/bgm_manager.py list-moods

# 按情绪匹配（返回真实文件路径，两级匹配：子目录优先，其次文件名关键词）
python -c "import sys; sys.path.insert(0,'scripts'); from bgm_manager import match_bgm_for_scene; print(match_bgm_for_scene('happy'))"

曲库结构建议：

D:bgm_librarytensedark_theme.mp3
D:bgm_libraryhappyupbeat_day.wav
D:bgm_libraryepic_cinematic.mp3   (根目录按文件名关键词匹配)

音效合成（无需外部素材）： 10 种可合成音效——heartbeat / footsteps / clock_tick / phone_ring / rain / wind / crowd / thunder_hit / glass_break / door_close。另有 car、sword 两种必须自备外部素材。

python scripts/bgm_manager.py synth --name heartbeat --output hb.mp3 --duration 5

人声 + BGM 混音 / 给视频挂 BGM（可直接调用，不必走全流程）：

# 混合人声与 BGM（bgm-volume 默认 0.3）
python scripts/bgm_manager.py mix --voice voice.mp3 --bgm bgm.mp3 --bgm-volume 0.25 --output mixed_audio.mp3

# 给已有视频添加 BGM
python scripts/bgm_manager.py add --video video.mp4 --bgm bgm.mp3 --bgm-volume 0.3 --output video_with_bgm.mp4

附加能力：Manim 数学/图形动画（可选）

主流程之外，animate_video.py 提供 Manim 驱动的图形动画，适合讲解类、数据类内容。

# 检查 Manim 等依赖是否就绪
python scripts/animate_video.py check_deps

# 渲染 Manim 场景（--preview 默认关闭，避免无 GUI 环境卡死）
python scripts/animate_video.py manim --input scene.py --scene MyScene --quality h --output out.mp4 --preview

# 把图片序列合成视频
python scripts/animate_video.py frames --frames-dir ./frames --fps 24 --audio voice.mp3 --output out.mp4

内置 6 个可直接复用的模板（scripts/manim_templates/）：opening_template.py（片头）、ending_template.py（片尾）、motion_template.py（运动动画）、text_animation_template.py（文字动画）、scene_transition_template.py（场景转场）、short_drama_template.py（短剧场景）。

Manim API 速查（动画类型、图形对象、中文字体、渲染命令）见 references/manim_quick_ref.md。

发布规格与素材参考

• 平台视频规格（抖音/快手/B站/小红书 + 通用导出设置）：references/platform_specs.md
• 免版权素材清单（BGM/音效/图片/视频来源 + 情绪搜索词）：references/free_resources.md

回退模式（无 API Key）

API 未配置时自动降级：

1. ImageGen 生成场景关键帧图片
2. FFmpeg Ken Burns 缓慢缩放
3. 这是降级方案，产出不是真正动画视频

用 --no-fallback 可关掉回退，让 API 失败直接报错，避免误把降级结果当正式产物。

失败排查

适用边界

适合： 剧情短剧、图文解说、商品/品牌宣传片、小说可视化、社媒短视频。

不适合：

• 需要逐帧精确控制的生产级动画（改用 Manim 分支或专业工具）
• 真人实拍素材的替换与增强
• 需要严格可复现的产出——生成结果有随机性，除非固定 --seed
• 法律文书、合同、需逐字保真的文本转换

成本提示： 即梦 API 按量计费，batch 模式会一次性消耗整部剧本的额度。建议先用 --draft（1.5-pro）或单场景试跑确认效果，再批量生成。

素材版权： BGM 曲库与参考素材需自行确保授权，技能内只提供合成音效和搜索指引，不附带版权素材。

依赖安装

python scripts/setup_deps.py

安装清单：Pillow、edge-tts、gTTS、pyttsx3、httpx、requests、pydub、FFmpeg/imageio-ffmpeg

脚本索引

5 种画风

korean_manga 是针对性最强的一种，基于抖音"一口气看完"长视频逆向提炼：中心聚焦近景构图、暖黄 LUT、4 层文字层级（剧情字幕 / 提示信息 / 水印 / 平台 UI）、星点粒子与呼吸式微动效。完整的画面参数、文字层级坐标与批量制作流程见 references/korean_manga_style.md。

输出规范

所有脚本均支持 --ratio：9:16（竖屏）/ 16:9（宽屏）/ 4:3（横屏）/ 1:1 / 3:4 / 21:9。

优先级：CLI --ratio > 剧本 JSON 的 aspect_ratio 字段 > 默认 9:16。

剧本生成、脚本解析、分镜计划、渲染合成四个环节都接受 --ratio，传入即写入或覆盖对应 JSON 字段；渲染阶段的 --ratio 会覆盖剧本里的设置。命令示例见上文各步骤。