🎬 story-to-animation

Turn a story idea into a finished AI-animated video in 5 steps.
Logline in — scripted, shot-listed, rendered, and merged animation out.

---

Claude drives the creative steps (story, characters, shot list) and pauses for your approval after each one. Python scripts drive the heavy lifting (image/video generation via kie.ai, final merge via FFmpeg) and are safe to re-run any time — they skip whatever's already been generated.

Pipeline

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)

Step	Skill	Runs as	Output
1	generating-story-from-logline	Claude	story.md
2	extracting-characters-and-backgrounds	Claude	characters.json, backgrounds.json
3	generating-character-and-background-images	script + kie.ai	./characters/*.png, ./backgrounds/*.png
4	creating-shot-list	Claude	shots.json
5	generating-composite-and-video	script + kie.ai + FFmpeg	./clips/*.mp4 → final_animation.mp4

Every step ends with a review gate — Claude shows you the output and waits for approval before moving on.

Requirements

Dependency	Required	Notes
Python 3.8+	✅	Runs the generation/merge scripts
FFmpeg	✅	Final clip merge (Step 5)
kie.ai API key	✅	Image + video generation
imgbb API key	✅	Permanent image hosting between steps

pip install -r requirements.txt

FFmpeg:

brew install ffmpeg        # Mac
winget install ffmpeg      # Windows
sudo apt install ffmpeg    # Linux

Setup

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

# 2. Install dependencies
pip install -r requirements.txt

# 3. Create .env
cp .env.example .env
# Open .env and fill in KIE_API_TOKEN + IMGBB_API_KEY

Skills live in .claude/skills/ inside the repo — Claude Code picks them up automatically, no manual install step needed.

Usage

Steps 1–2 — Claude. Paste the corresponding SKILL.md into Claude, give it a logline, and let it write the story and extract characters/backgrounds. Claude stops after each step for your approval.

Step 3 — generate images:

python .claude/skills/03-generating-character-and-background-images/scripts/generate_images.py

Step 4 — Claude. Paste the Step 4 SKILL.md into Claude to create shots.json.

Step 5 — generate video:

# Bulk mode — all shots at once
python .claude/skills/05-generating-composite-and-video/scripts/generate_videos.py

# Per-shot mode — one shot at a time, to review each clip
python .claude/skills/05-generating-composite-and-video/scripts/generate_videos.py --shot shot_001

# Merge into the final video
python .claude/skills/05-generating-composite-and-video/scripts/merge_clips.py

Project Directory Structure

my-animation-project/
├── .env                    # API keys (do not commit)
├── story.md                # Screenplay (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       # Final output (Step 5)

Tips

• Consistency: describe characters in full detail in every veo_prompt (colors, outfit, distinctive features).
• Reuse backgrounds: reuse the same bg_id across multiple scenes to save generation time.
• Per-shot mode: use --shot to review each clip before continuing.
• Retry: scripts automatically retry on transient API errors.
• Re-run safe: scripts skip files that already exist — safe to re-run anytime.

License

MIT