# THỬ NGHIỆM IMAGE-TO-VIDEO QUA HUGGING FACE SPACE (ZERO-GPU FREE API)

> **Cập nhật:** Tháng 10 năm 2026  
> **Mục đích:** Thay thế hoàn toàn giao diện Web thủ công của Muse.ai bằng phương thức gọi API ngầm (Headless API), chi phí **0 VNĐ ($0.00)**, không phụ thuộc DOM trình duyệt, không Captcha.

---

## 1. TỔNG QUAN CÁC MÔ HÌNH HỖ TRỢ

| Mã Model (`--model`) | Tên Mô Hình | Space ID | Thời Gian Xử Lý | Đặc Điểm |
| :--- | :--- | :--- | :--- | :--- |
| `ltx` (Mặc định) | **LTX-Video Distilled** | `Lightricks/ltx-video-distilled` | **15 - 30 giây** | Siêu nhanh, chuyển động mượt, phản hồi trực tiếp. Phù hợp test lặp lại nhiều lần. |
| `wan21` | **Alibaba Wan 2.1** | `Wan-AI/Wan2.1` | **60 - 120 giây** | Chất lượng điện ảnh Á Đông hàng đầu thế giới 2026, tái tạo chi tiết trang phục, ánh sáng cổ phong xuất sắc. |
| `cogvideox` | **CogVideoX-5B** | `zai-org/CogVideoX-5B-Space` | **45 - 90 giây** | Rất ổn định, góc máy điện ảnh chuẩn xác. |

---

## 2. HƯỚNG DẪN SỬ DỤNG NHANH

### Cách 1: Thử nghiệm với một ảnh bất kỳ
```bash
# Render bằng LTX-Video (nhanh nhất)
python gradio_version/render_test.py --image "04_Assets/characters/thuy_kieu_maiden_16yo/front.png" --prompt "cinematic slow portrait shot, ancient Vietnamese dress, gentle breeze blowing hair, soft natural lighting, 24fps" --model ltx

# Render bằng Alibaba Wan 2.1 (chất lượng điện ảnh cao nhất)
python gradio_version/render_test.py --image "04_Assets/characters/thuy_kieu_maiden_16yo/front.png" --prompt "ancient palace courtyard, cinematic lighting, 24fps" --model wan21
```

### Cách 2: Render trực tiếp theo Shot ID của phim
Tự động nạp Prompt và Start Frame tương ứng trong dự án:
```bash
python gradio_version/render_test.py --shot-id ep01_scene01_shot01 --model ltx
```

---

## 3. CƠ CHẾ ZERO-GPU & TOKEN TÙY CHỌN
- Không cần tài khoản hay thẻ tín dụng: Mặc định script gọi vào ZeroGPU công khai của Hugging Face hoàn toàn miễn phí.
- **Tùy chọn tăng tốc độ (Nâng cao):** Nếu có tài khoản Hugging Face (kể cả Free), bạn có thể gán biến môi trường `HF_TOKEN` hoặc truyền qua cờ `--token hf_xxx` để được ưu tiên trong hàng đợi khi Space đông lượt truy cập:
  ```bash
  $env:HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

---

## 4. TÍCH HỢP VÀO PRODUCTION PIPELINE
Video sau khi sinh được tự động:
1. Lưu vào thư mục `gradio_version/outputs/`.
2. Tự động trích xuất **Tail Frame** (`*_tail.jpg`) để tiếp tục nối tiếp cho shot kế tiếp (Head-Tail Chaining) mà không làm đứt gãy mạch phim.