How to Set Up and Run Pixelle-Video Locally: Complete Installation Guide

To run Pixelle-Video locally, install uv and ffmpeg, clone the repository, and launch the Streamlit UI with uv run streamlit run web/app.py.

Pixelle-Video is an open-source AI platform for generating short videos from text prompts. This guide walks you through the complete local setup process using source code from the AIDC-AI/Pixelle-Video repository.

Prerequisites: Install uv and ffmpeg

Before cloning the repository, you need two system dependencies: uv (a fast Python package manager) and ffmpeg (for video/audio encoding).

Install uv

Follow the official installation guide at docs.astral.sh/uv.

Install ffmpeg

The README documents these steps at lines 1020-1026:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
• Windows: Download from ffmpeg.org/download.html and add bin to your PATH

Clone and Launch the Web UI

Once dependencies are installed, set up the project:

git clone https://github.com/AIDC-AI/Pixelle-Video.git
cd Pixelle-Video

Launch the Streamlit web interface with:

uv run streamlit run web/app.py

This command matches the start_web.sh helper script (lines 7-9)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/start_web.sh#L7-L9】. The entry point at web/app.py (lines 40-58) sets up multi-page navigation and runs the UI【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/web/app.py#L40-L58】.

The UI opens at http://localhost:8501 by default.

(Optional) Run the API Server Directly

If you prefer programmatic access or want to build custom clients, launch the FastAPI backend separately:

uv run python api/app.py

The server initialization at api/app.py (lines 71-85) prints a startup banner and launches uvicorn【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/api/app.py#L71-L85】. Configuration including host, port, CORS settings, and API prefixes lives in api/config.py (lines 24-46)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/api/config.py#L24-L46】.

Configure Your API Keys and Services

Before generating videos, you must configure external services in the System Configuration panel (⚙️):

Setting	Required For	Typical Value
LLM API	Script generation	OpenAI, Claude, or local endpoint
Image generation	Visual assets	ComfyUI at http://127.0.0.1:8188 or RunningHub API key
TTS workflow	Voice narration	Edge-TTS, Index-TTS, or voice cloning with reference audio

These settings map to the config.example.yaml schema, which the UI copies to config.yaml at runtime.

Generate Your First Video

With configuration complete:

1. Navigate to the Home page (web/pages/1_🎬_Home.py)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/web/pages/1_%F0%9F%8E%AC_Home.py】
2. Enter a topic or paste a full script
3. Select a template (e.g., video_default.html from templates/)
4. Click 🎬 Generate Video

Progress bars display each pipeline stage: script generation → image synthesis → voice synthesis → final video rendering. The output MP4 appears in the UI and saves to the output/ directory.

Windows One-Click Installation

For Windows users wanting a no-installation experience, download the Windows package from the release section (documented at README lines 82-90)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/README.md#L82-L90】.

The bundle includes:

• Pre-compiled ffmpeg.exe
• All Python dependencies via uv
• Double-clickable start.bat (equivalent to start_web.sh)

Extract and run start.bat — no manual dependency installation required.

Example API Calls

With the API server running, interact programmatically:

# Health check

curl http://localhost:8000/health

# Generate narration script

curl -X POST http://localhost:8000/api/content/narration \
     -H "Content-Type: application/json" \
     -d '{"topic":"Why reading every day matters"}'

# Synchronous video generation (videos under 30 seconds)

curl -X POST http://localhost:8000/api/video/generate/sync \
     -H "Content-Type: application/json" \
     -d '{
           "topic":"The future of AI",
           "template":"video_default.html",
           "tts_workflow":"edge_tts.json",
           "image_workflow":"image_flux.json"
         }'

The OpenAPI specification is available at /openapi.json (configured in api/config.py).

Key Architecture Files

File	Purpose	Direct Link
README.md	Documentation and feature overview	View
start_web.sh	Bash launcher for Streamlit UI	View
api/app.py	FastAPI entry point	View
api/config.py	Runtime configuration	View
api/tasks/manager.py	Asynchronous task orchestration	View
web/app.py	Streamlit entry point	View
web/pages/1_🎬_Home.py	Main video generation interface	View
config.example.yaml	Configuration template	View

Summary

To set up and run Pixelle-Video locally:

• Install prerequisites: uv and ffmpeg are required before cloning
• Launch the UI: uv run streamlit run web/app.py starts the web interface at localhost:8501
• Configure services: Add LLM, image generation, and TTS credentials in the System Configuration panel
• Generate videos: Enter a topic, select a template, and click the generate button
• Optional API access: Run uv run python api/app.py for direct backend access

Windows users can skip installation entirely by downloading the pre-built Windows package with start.bat.

Frequently Asked Questions

What are the minimum hardware requirements for running Pixelle-Video locally?

Pixelle-Video itself is lightweight and runs on CPU, but video generation performance depends on your chosen image and TTS backends. For local ComfyUI image generation, a CUDA-capable GPU with at least 8GB VRAM is recommended. Edge-TTS requires no local GPU. Always ensure sufficient disk space for ffmpeg temporary files and output videos.

Can I use Pixelle-Video without installing Python dependencies?

Yes. Windows users can download the Windows one-click package from the releases page. This bundle includes pre-compiled ffmpeg.exe, all Python dependencies packaged via uv, and a start.bat file that launches the interface immediately. No manual uv or ffmpeg installation is required.

How do I connect Pixelle-Video to my own ComfyUI instance?

In the System Configuration panel (⚙️), set the Image Generation option to "Local ComfyUI" and enter your ComfyUI URL (default: http://127.0.0.1:8188). Ensure your ComfyUI instance is running with the required model checkpoints and the workflow JSON files from workflows/selfhost/*.json are accessible. The backend communicates via the ComfyUI REST API defined in the workflow utilities.

What is the difference between synchronous and asynchronous video generation?

Synchronous generation (/api/video/generate/sync) blocks until completion and is suitable for videos under 30 seconds. The API returns the final MP4 directly. Asynchronous generation submits a task to the queue managed by api/tasks/manager.py and returns a task ID immediately. Poll the status endpoint or use WebSocket updates to track progress. Asynchronous mode handles longer videos and concurrent requests without blocking the API server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}