Story-to-Animation Pipeline

Biến một câu chuyện ý tưởng thành video hoạt hình AI hoàn chỉnh trong 5 bước, chạy trực tiếp với Claude + kie.ai.

---

Pipeline Overview

Logline → story.md → characters.json / backgrounds.json → images → shots.json → video clips → final_animation.mp4
  Step 1     Step 2            Step 3 (script)            Step 4      Step 5 (script)

---

Yêu cầu

• Python 3.8+
• FFmpeg (cho bước merge)
• API keys: kie.ai + imgbb

pip install -r requirements.txt

FFmpeg:

# Mac
brew install ffmpeg

# Windows
winget install ffmpeg

# Linux
sudo apt install ffmpeg

---

Cài đặt

# 1. Clone repo
git clone https://github.com/your-username/story-to-animation.git
cd story-to-animation

# 2. Cài dependencies
pip install -r requirements.txt

# 3. Tạo .env
cp .env.example .env
# Mở .env và điền KIE_API_TOKEN + IMGBB_API_KEY

# 4. Cài skills vào Claude
# Copy thư mục skills/ vào ~/.claude/skills/

---

Sử dụng

Bước 1–2: Dùng Claude

Paste SKILL.md tương ứng vào Claude, cung cấp logline và để Claude viết story + extract characters/backgrounds.

Mỗi bước Claude sẽ dừng lại và chờ bạn duyệt trước khi tiếp tục.

Bước 3: Generate ảnh

cd /path/to/your/project
python ~/.claude/skills/generating-character-and-background-images/scripts/generate_images.py

Bước 4: Dùng Claude

Paste SKILL.md Step 4 vào Claude để tạo shots.json.

Bước 5: Generate video

# Bulk mode — tất cả shot cùng lúc
python ~/.claude/skills/generating-composite-and-video/scripts/generate_videos.py

# Per-shot mode — từng shot một (để duyệt từng clip)
python ~/.claude/skills/generating-composite-and-video/scripts/generate_videos.py --shot shot_001
python ~/.claude/skills/generating-composite-and-video/scripts/generate_videos.py --shot shot_002

# Merge thành video cuối
python ~/.claude/skills/generating-composite-and-video/scripts/merge_clips.py

---

Cấu trúc thư mục project

my-animation-project/
├── .env                    # API keys (không commit)
├── story.md                # Kịch bản (Step 1)
├── characters.json         # Character prompts + image_url (Step 2-3)
├── backgrounds.json        # Background prompts + image_url (Step 2-3)
├── shots.json              # Shot list + veo_prompts (Step 4)
├── characters/             # Reference images 1:1 (Step 3)
├── backgrounds/            # Background images 16:9 (Step 3)
├── composites/             # Composited scene images (Step 5)
├── clips/                  # Video clips per shot (Step 5)
└── final_animation.mp4     # Output cuối (Step 5)

---

Tips

• Consistency: Mô tả nhân vật thật chi tiết trong mọi veo_prompt (màu sắc, trang phục, đặc điểm nổi bật)
• Reuse backgrounds: Dùng lại cùng bg_id cho nhiều scene → tiết kiệm thời gian generate
• Per-shot mode: Dùng --shot để duyệt từng clip trước khi tiếp tục
• Retry: Script tự retry 3 lần nếu API lỗi tạm thời
• Re-run safe: Script bỏ qua file đã tồn tại — re-run an toàn bất cứ lúc nào

---

License

MIT