Capy 影片生成技能 - 腳本轉影片流程 是做什麼的?
從腳本或點子生成完整的多鏡頭影片,且所有場景中角色臉部保持一致。專為 HappyCapy AI Gateway 構建。經過 300 次實驗驗證,臉部距離改善 70%。
概述
ViMax 透過自動化流程將文字腳本轉換為完整影片:
- 從腳本中提取角色,包含詳細的身體特徵
- 為每個角色生成正面、側面、背面肖像
- 設計逐鏡頭的分鏡表
- 將每個鏡頭分解為第一影格、最後影格與動作描述
- 建立鏡頭關係的攝影機樹
- 使用參考影像選擇(臉部身份為最高優先級)生成影格
- 從影格生成影片片段
- 拼接成最終影片
安裝位置
ViMax 流程代碼位於:/home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax/
所有指令都必須從此目錄使用 venv 執行:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
先決條件
AI_GATEWAY_API_KEY環境變數(在 HappyCapy 中自動設定)- Python venv 位於
.venv/(已設定完成)
快速開始
腳本轉影片
編輯入口腳本中的腳本、需求與風格,然後執行:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
點子轉影片
從簡短點子生成(先自動產生腳本):
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_idea2video.py
程式化使用
import asyncio
from langchain.chat_models import init_chat_model
from tools.render_backend import RenderBackend
from utils.config_loader import load_config
from pipelines.script2video_pipeline import Script2VideoPipeline
config = load_config("configs/happycapy_script2video.yaml")
chat_model = init_chat_model(**config["chat_model"]["init_args"])
backend = RenderBackend.from_config(config)
pipeline = Script2VideoPipeline(
chat_model=chat_model,
image_generator=backend.image_generator,
video_generator=backend.video_generator,
working_dir=config["working_dir"],
)
# 執行流程
asyncio.run(pipeline(
script="在此輸入您的腳本...",
user_requirement="總共不超過 8 個鏡頭。",
style="電影風格,溫暖燈光"
))
流程
Script2VideoPipeline
- 輸入:格式化的劇本/腳本,包含角色對話與場景描述
- 輸出:拼接完成的影片,位於
{working_dir}/final_video.mp4 - 設定檔:
configs/happycapy_script2video.yaml
Idea2VideoPipeline
- 輸入:簡短的點子/概念(1-3 段落)
- 輸出:自動產生腳本,然後生成影片
- 設定檔:
configs/happycapy_idea2video.yaml
設定
HappyCapy 設定檔位於 configs/happycapy_script2video.yaml:
chat_model:
init_args:
model: gpt-4.1
model_provider: openai
api_key: ${AI_GATEWAY_API_KEY}
base_url: https://ai-gateway.happycapy.ai/api/v1/openai/v1
image_generator:
class_path: tools.ImageGeneratorHappyCapyAPI
init_args:
api_key: ${AI_GATEWAY_API_KEY}
model: google/gemini-3.1-flash-image-preview
video_generator:
class_path: tools.VideoGeneratorHappyCapyAPI
init_args:
api_key: ${AI_GATEWAY_API_KEY}
model: google/veo-3.1-generate-preview
working_dir: .working_dir/script2video
關鍵元件
代理器(AI 處理)
| 代理器 | 檔案 | 用途 |
|---|---|---|
| CharacterExtractor | agents/character_extractor.py | 從腳本中提取角色,包含靜態/動態特徵 |
| CharacterPortraitsGenerator | agents/character_portraits_generator.py | 為每個角色生成正面/側面/背面肖像 |
| StoryboardArtist | agents/storyboard_artist.py | 設計逐鏡頭分鏡表,包含第一/最後影格與動作 |
| ReferenceImageSelector | agents/reference_image_selector.py | 為每個影格選擇最佳參考影像(臉部身份為第一優先) |
| CameraImageGenerator | agents/camera_image_generator.py | 建立攝影機樹並生成轉場影片 |
| BestImageSelector | agents/best_image_selector.py | 從候選影像中選擇最佳生成的影像 |
| Screenwriter | agents/screenwriter.py | 從點子生成腳本 |
工具(生成後端)
| 工具 | 檔案 | 用途 |
|---|---|---|
| ImageGeneratorHappyCapyAPI | tools/image_generator_happycapy_api.py | 透過 HappyCapy Gateway 進行影像生成(Gemini) |
| VideoGeneratorHappyCapyAPI | tools/video_generator_happycapy_api.py | 透過 HappyCapy Gateway 進行影片生成(Veo) |
| RenderBackend | tools/render_backend.py | 用於從設定實例化生成器的工廠 |
介面(資料模型)
CharacterInScene- 包含識別碼、靜態特徵、動態特徵的角色ShotDescription- 包含第一影格描述、最後影格描述、動作描述、變化類型的鏡頭Camera- 包含父子關係的攝影機Frame- 包含鏡頭索引、影格類型、可見角色的影格ImageOutput/VideoOutput- 包含儲存方法的生成輸出
臉部身份一致性(關鍵)
此流程包含經 257 次實驗驗證的臉部身份改善(臉部距離改善 70%,從 0.74 降至 0.22):
內建保護機制
-
參考影像選擇器:選擇參考影像時,臉部身份為第一優先。當角色臉部可見時,正面肖像始終包含在內。
-
角色肖像:增強的提示詞可生成身份關鍵細節(確切的鼻形、眼距、下巴線條、區別標記),利於跨場景辨識。
-
影片提示臉部鎖定:每個影片生成提示詞前綴都會加上臉部身份指令,要求角色臉部在整個片段中與起始影格保持一致。
使用 ViMax 的最佳實務
- 超詳細角色描述:在腳本的角色介紹中包含種族、年齡、髮質/髮型/髮色、眼睛形狀、鬍鬚、眼鏡、膚色、體型與區別標記
- 極特寫鏡頭:至少為每個角色包含一個極特寫鏡頭,以鎖定身份
- 一致的燈光:指定跨場景相似的燈光,防止臉部偏移
- 使用者提供的參考照片:將照片放入工作目錄,並作為
character_portraits_registry傳入,跳過 AI 肖像生成
無效的方法
- 複雜的提示工程(viseme 變形、音素錨定)無法改善臉部身份
- 簡單直接的提示詞搭配詳細身體描述,效果優於花俏的提示詞
- 無法對外部音訊進行唇形同步(Veo 會生成自己的內部音訊)
詳情請參閱 ViMax 目錄中的 FACE_IDENTITY_GUIDE.md。
輸出結構
執行後,工作目錄包含:
.working_dir/script2video/
characters.json # 提取的角色
character_portraits_registry.json # 肖像路徑註冊表
character_portraits/ # 生成的肖像
0_CharacterName/
front.png
side.png
back.png
storyboard.json # 鏡頭描述
camera_tree.json # 攝影機關係
shots/
0/
shot_description.json
first_frame.png
last_frame.png (如果是中/大變化)
video.mp4
1/
...
final_video.mp4 # 最終拼接輸出
自訂
使用您自己的參考照片
若要使用真實照片而非 AI 生成的肖像:
# 建立指向您照片的肖像註冊表
character_portraits_registry = {
"Alice": {
"front": {"path": "/path/to/alice_front.png", "description": "Alice 正面"},
"side": {"path": "/path/to/alice_side.png", "description": "Alice 側面"},
"back": {"path": "/path/to/alice_back.png", "description": "Alice 背面"},
}
}
# 傳入流程(跳過肖像生成)
await pipeline(
script=script,
user_requirement=user_requirement,
style=style,
character_portraits_registry=character_portraits_registry,
)
更換模型
編輯 YAML 設定以使用不同模型:
- 影像:
google/gemini-3.1-flash-image-preview(建議用於臉部身份) - 影片:
google/veo-3.1-generate-preview(建議)或openai/sora-2 - 對話:
gpt-4.1(建議)或任何 OpenAI 相容模型
疑難排解
「No module named 'tools'」或類似匯入錯誤
從 ViMax 根目錄執行:
cd /home/node/a0/workspace/527fb591-1439-4b5b-ad5d-90f972773f95/workspace/tmp/ViMax
.venv/bin/python main_happycapy_script2video.py
API 速率限制錯誤
在 YAML 設定中降低 max_requests_per_minute。
生成影片中臉部身份偏移
- 在腳本的角色描述中加入更多身體細節
- 使用使用者提供的參考照片而非 AI 生成的肖像
- 為重要角色包含極特寫鏡頭
- 保持跨場景燈光一致