Capy Video Gen Skill - スクリプトから動画へのパイプライン
スクリプトやアイデアから、すべてのシーンで一貫したキャラクターの顔を持つマルチショット動画を生成します。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では自動設定).venv/にあるPython 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
設定
configs/happycapy_script2video.yaml のHappyCapy設定:
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- 識別子、static_features、dynamic_featuresを持つキャラクターShotDescription- ff_desc、lf_desc、motion_desc、variation_typeを持つショットCamera- 親子関係を持つカメラFrame- shot_idx、frame_type、可視キャラクターを持つフレームImageOutput/VideoOutput- 保存メソッドを持つ生成出力
顔の同一性の一貫性(重要)
このパイプラインには、257回の実験で検証された顔の同一性の改善が含まれています(顔の距離指標を70%改善、0.74から0.22へ)。
組み込みの保護機能
-
参照画像セレクター: 参照画像を選択する際、顔の同一性が最優先事項です。キャラクターの顔が見える場合、正面ポートレートは常に含まれます。
-
キャラクターポートレート: 拡張されたプロンプトにより、シーンをまたいだ認識のための同一性に重要な詳細(正確な鼻の形状、目の間隔、顎のライン、識別マーク)が生成されます。
-
動画プロンプト顔ロック: すべての動画生成プロンプトには、クリップ全体を通じてキャラクターの顔が開始フレームと同一であることを要求する顔同一性指示が前置されます。
ViMax使用時のベストプラクティス
- 超詳細なキャラクター説明: 人種、年齢、髪の質感/スタイル/色、目の形、顔の毛、眼鏡、肌のトーン、体格、識別マークをスクリプトのキャラクター紹介に含める
- 極端なクローズアップショット: キャラクターごとに少なくとも1つの極端なクローズアップを含めて同一性を固定する
- 一貫した照明: シーン間で同様の照明を指定して顔のドリフトを防ぐ
- ユーザー提供の参照写真: 写真を作業ディレクトリに配置し、
character_portraits_registryとして渡すとAIポートレート生成をスキップできる
機能しないもの
- 複雑なプロンプトエンジニアリング(ビセームモーフィング、フォニームアンカリング)は顔の同一性を改善しない
- 詳細な身体的特徴を含むシンプルで直接的なプロンプトが、巧妙なプロンプトよりも優れている
- 外部オーディオへのリップシンクは不可能(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生成ポートレートの代わりにユーザー提供の参照写真を使用
- 重要なキャラクターには極端なクローズアップショットを含める
- シーン間で照明を一貫させる