Skip to content
ChatGPT & LLMs

AIMovie Install Guide: Deploy AI Movie Stack

Install AIMovie from GitHub main: Python 3.12, uv, Node 18+, ports 8666/36310, Docker via deploy.sh, and real 花屏/GOP glitch recovery.

7 min readIntermediate

The #1 mistake with an AI movie stack is treating “install” as “sign up for a web generator.” You burn API credits, never own the pipeline, and have no way to re-run a single bad shot. Reverse that: deploy AIMovie on your machine first, wire keys second, then generate.

AIMovie (johnson7788/AIMovie, MIT) is self-hosted idea→script→storyboard→image→video – series mode and single-clip mode in one repo. As of March 2025 research there are no GitHub Release tags (~71 commits on main, low star count at check time). Clone main. Your deploy identity is the commit hash, not a semver pin.

Owning the stitch step changes how you debug. A SaaS UI hides the bad intermediate MP4; here that file sits on disk and you can delete exactly one shot without rerunning the whole series. That is the point of this stack – not another “write a prompt, export CapCut” essay.

System requirements before you touch AI movie tooling

Per the project README you need:

Piece Minimum Notes
Python 3.12+ Backend FastAPI runtime
Node.js 18+ Vue 3 + Vite frontend
uv latest Astral uv package manager
ffmpeg on PATH / resolvable start.sh asserts it via utils.video._resolve_ffmpeg_exe
Docker Engine + Compose Only if you use deploy.sh

RAM and disk are not hard-coded. Budget multi-GB free under backend/.working_dir for task artifacts and API downloads. Host GPU? Optional. Generation is cloud-API driven (Volcengine ARK, Google, Hunyuan, MiniMax, OpenAI, GPUGeek, Agnes) – the box mostly orchestrates and stitches.

Official download source (not the README placeholder)

The README still shows git clone https://github.com/your-org/AIMovie.git. Wrong owner. Live path:

git clone https://github.com/johnson7788/AIMovie.git
cd AIMovie
git rev-parse --short HEAD # record this; no release tags

That is the only official source. Images build locally as aimovie-backend:latest / aimovie-frontend:latest – nothing to pull from a public Hub tag.

Install AIMovie step by step (native, recommended for debug)

  1. Install uv, then Python 3.12 if needed: 
    # macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
# irm https://astral.sh/uv/install.ps1 | iex
uv python install 3.12
  2. Backend deps: 
    cd backend
uv sync
# note: start.sh forces --index-url https://pypi.tuna.tsinghua.edu.cn/simple
# mirror fails outside CN? run plain: uv sync
  3. Frontend deps: 
    cd ../frontend
npm install
  4. First-time config – copy env and fill only providers you will use: 
    cp backend/env_example backend/.env

Lean .env from env_example (model default as shipped on main – this may have changed):

ARK_API_KEY=... # Volcengine Doubao - common CN path
ARK_MODEL=doubao-seedance-1-0-pro-fast-251015
GOOGLE_API_KEY=... # Nanobanana / Veo
OPENAI_API_KEY=... # or any OpenAI-compatible LLM base later
GPUGEEK=... # optional proxy for Seedream 5 / Seedance 2 / Vira
SERVER_PORT=8666
VITE_REQUEST_BASE_URL=http://127.0.0.1:8666

Leave unused keys blank. Hunyuan needs separate HUNYUAN_API_KEY and HUNYUAN_VISION_API_KEY if you go that route.

Pro tip: One working image path + one video path + one LLM key beats filling every blank. Empty keys just mean that provider will not show up in /api/models.

First boot and verification

Native one-shot:

# Linux / macOS
chmod +x start.sh && ./start.sh
# Windows
.start.bat

start.sh needs uv, node, npm, curl. It pins uv sync to the Tsinghua PyPI mirror, clears non-Python holders of port 8666, starts uv run python main.py, then polls /health for up to ~120s looking for JSON with status and ok. Vite follows with VITE_REQUEST_BASE_URL aimed at the backend. Logs: logs/.

Two terminals instead:

cd backend && uv run python main.py
cd frontend && npm run dev

Verify:

curl -fsS http://127.0.0.1:8666/health
# API docs
open http://localhost:8666/docs
# UI (native)
open http://localhost:36310/aimovie/

Register via the top-right login flow (account/password only as of the README). Once in, hit GET /api/models and GET /api/styles so you know keys resolved.

Docker path:

chmod +x deploy.sh && ./deploy.sh
# frontend: http://localhost:8088/aimovie/
# backend: http://localhost:8666/health
docker compose logs -f
docker compose down # stop

deploy.sh runs compose up --build -d. Host map: UI 8088, API 8666. Compose binds workdir/logs volumes and mounts ./backend/tasks.db; healthcheck curls container-local /health.

Common install and pipeline failures (real messages)

  • Error: 'uv' not found / missing node/npm/curl – start.sh exits immediately. Install the four binaries and re-open the shell so PATH updates.
  • Backend timeout / process dies – read logs/backend-*.log. Often missing .env, bad key, or ffmpeg assert failed during the preflight uv run python -c ..._resolve_ffmpeg_exe.
  • Port 8666 weirdness – script kills IDE forwarders that are not Python; if a real second AIMovie is already healthy, it reuses it.
  • Visual glitch / 花屏 after a long series render – project doc 花屏问题.md shows two layers. MoviePy write_videofile without codec="libx264" on macOS can emit visually corrupted H.264 that still “passes” ffmpeg validate (idea2video once lagged script2video on that flag). Separately, bad upstream shots – Vira/GPUGeek low unique-color / near-solid frames – poison scene joins and break later GOPs.

The catch is resume. Delete only top-level final_video.mp4 and the pipeline happily reuses scene_*/final_video.mp4 plus the bad shot video.mp4. You must clear all three, then re-trigger:

TASK_DIR=backend/.working_dir/idea2video/<task_id>
rm "$TASK_DIR/scene_X/shots/Y/video.mp4"
rm "$TASK_DIR/scene_X/final_video.mp4"
rm "$TASK_DIR/final_video.mp4"
# re-trigger the same task - good shots stay cached

Same shot fails again? The generator+prompt+first_frame combo is unstable – change the still or provider, not just the stitch step.

Upgrade and uninstall

Upgrade = pull main and rebuild.

cd AIMovie
git pull
cd backend && uv sync
cd ../frontend && npm install
# restart start.sh / start.bat

Docker: git pull && ./deploy.sh (compose up –build -d).

Uninstall native: Ctrl+C the script, remove the clone. Optional media wipe: rm -rf backend/.working_dir backend/tasks.db logs. Docker: docker compose down, then drop named aimovie workdir/log volumes if you want a clean slate. Keys live only in backend/.env – delete that file when the box is done.

Port map after a long day: native UI 36310, Docker UI 8088, API always 8666 unless you change SERVER_PORT. Mix those up once and you will swear the frontend “is blank” while the API is fine.

FAQ

Does AIMovie run fully offline with no API keys?

No. The app is the orchestrator. Image, video, and LLM calls go to configured cloud providers. Without at least one key in backend/.env, generation endpoints will not expose usable models.

Native start vs Docker – which should I pick first?

Wire keys with ./start.sh (or start.bat). You want live logs and a fast restart loop. Move to ./deploy.sh when the stack should survive logout: backend image, frontend on host 8088, workdir volume kept across restarts. Same .env either way. Public tunnels? Repo ships start-ngrok.* helpers – leave them alone until core install is boring.

I got a finished MP4 that looks fine in ffmpeg but is glitched mid-film. Is the install broken?

Not the install. Bad shot → MoviePy join → scrambled later GOPs even when containers validate. Fix shot file, scene final, top final (see recovery block above), re-run. Prefer providers that stay stable on your reference stills.

Next action: clone https://github.com/johnson7788/AIMovie.git, copy backend/env_example → .env with one LLM + one video key, run ./start.sh, confirm curl http://127.0.0.1:8666/health, register in the UI, then fire a short single-clip job before any series-length burn.

Related AI Tools