---
title: Wan2.1 VACE Face Preserving Video Generation
emoji: 🎬
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: apache-2.0
---

# Wan2.1 VACE 顔保持動画生成システム

## 概要

このプロジェクトは、Alibaba発のWan2.1 VACEモデルを使用して、参照画像の顔を保持しながら動画を生成するシステムです。開始フレームと終了フレームを指定することで、その間を自然に補間する動画を生成できます。

## 主な機能

- **顔のアイデンティティ保持**: 参照画像の人物の顔を動画全体で維持
- **フレーム補間**: 開始・終了フレーム間の自然な動きを生成
- **高品質出力**: 512x512解像度、24fps、約10秒の動画生成
- **簡単な操作**: Gradio UIによる直感的なインターフェース
- **2つの生成モード**: 動画生成（開始・終了フレーム）と画像生成（プロンプトベース）
- **REST API**: プログラムから利用可能なAPIエンドポイント

## 技術仕様

### 動画生成モード
- **モデル**: Wan2.1-FLF2V-14B-720P
- **解像度**: 1280×720ピクセル
- **フレームレート**: 24fps
- **動画長**: 約10秒（240フレーム）

### 画像生成モード
- **モデル**: Wan2.1-VACE-1.3B
- **解像度**: 832×480ピクセル
- **出力**: 単一フレーム画像

### システム要件
- **推奨GPU**: NVIDIA A10以上（24GB VRAM）

## 使い方

### UI経由での利用

#### 動画生成タブ
1. **参照画像をアップロード**: 動画内で保持したい人物の顔画像
2. **開始フレームをアップロード**: 動画の最初のフレーム
3. **終了フレームをアップロード**: 動画の最後のフレーム
4. **「動画生成」ボタンをクリック**: 処理には数分かかります

#### 画像生成タブ
1. **参照画像をアップロード**: 保持したい人物の顔画像
2. **プロンプトを入力**: 生成したい画像の説明文
3. **「画像生成」ボタンをクリック**: 画像が生成されます

### API経由での利用

#### 動画生成API
```bash
curl -X POST \
-F ref=@ref.png \
-F first=@start.png \
-F last=@end.png \
https://huggingface.co/spaces/あなたのID/Space名/generate_video
```

#### 画像生成API
```bash
curl -X POST \
-F ref=@ref.png \
-F prompt="サンプルプロンプト" \
https://huggingface.co/spaces/あなたのID/Space名/generate_image
```

## インストールと実行

### ローカル環境での実行

```bash
# リポジトリをクローン
git clone https://github.com/yourusername/wan2.1-vace.git
cd wan2.1-vace

# 依存関係をインストール
pip install -r requirements.txt

# モデルをダウンロード（初回のみ）
chmod +x download_models.sh
./download_models.sh

# アプリケーションを起動
python app.py
```

### Hugging Face Spacesでの実行

このプロジェクトはHugging Face Spacesで直接実行できるよう設計されています。GPUインスタンスを使用することを推奨します。

## プロジェクト構造

```
wan2.1-vace/
├── app.py                  # メインのGradioアプリケーション（UIとAPI）
├── wan_runner.py          # 生成処理を実装するPythonコード
├── download_models.sh     # モデルダウンロードスクリプト
├── model_download.py      # モデルダウンロードユーティリティ（旧版）
├── vace_integration.py    # VACEとWan2.1の統合ヘルパー（旧版）
├── config.py              # アプリケーション設定
├── requirements.txt       # Python依存関係
├── examples/              # サンプル画像
├── workspace/             # 作業用一時ディレクトリ
├── results/               # 生成された動画の保存先
└── cache/                 # モデルキャッシュ
```

## 注意事項

- GPU搭載環境での実行を強く推奨します
- 初回実行時は2つのモデル（合計約35GB）のダウンロードが必要です
  - Wan2.1-VACE-1.3B: 画像生成用
  - Wan2.1-FLF2V-14B-720P: 動画生成用
- プロンプトは英語または中国語で記述すると良い結果が得られます
- 生成には数分かかる場合があります

## ライセンス

このプロジェクトはApache License 2.0の下で公開されています。

## 謝辞

- [Wan2.1](https://github.com/Wan-Video/Wan2.1) - Alibaba
- [VACE](https://github.com/ali-vilab/VACE) - Ali-ViLab

## 参考資料

- [構築ガイド](構築ガイド.md)
- [作業タスク](作業タスク.md)