VideoForge Studio

Unified control plane for AI video generation — orchestrate 6 engines (self-hosted + commercial API) behind one REST API.

51/51 tests passing · 6 engines · 1 API

English · 简体中文

---

What it is, in 30 seconds

• Six engines, one API. mock, minimax_h3, wan, cogvideo, hunyuan and openai_compatible all implement the same BaseEngine contract. Switch engines with one field in the request body — your application code never changes.
• Production task plane, not a demo script. Celery + Redis job queues with a queued → running → succeeded / failed / cancelled state machine, retries with backoff, per-user quotas, scheduled cleanup, and an automatic in-process fallback when Redis is absent.
• A Mock engine means no GPU is needed to run CI. The built-in mock engine produces a real MP4 container offline, with no API key and no accelerator, so the whole path — job → engine → video → evaluation — is exercisable on a laptop and inside a CI runner. This is the difference between "clone it and it runs" and "clone it and go rent an H100".

---

Quickstart

Three commands. The default engine is mock, so nothing below needs a GPU or an API key.

# 1 — boot the stack (Postgres + Redis + API + Celery worker)
VIDEOFORGE_SECRET_KEY=dev-secret docker compose -f docker/docker-compose.yml up -d

# 2 — create a user and export a JWT
curl -s -X POST localhost:8000/api/v1/auth/register -H 'Content-Type: application/json' \
  -d '{"email":"dev@example.com","username":"dev","password":"devpassword"}' >/dev/null && \
TOKEN=$(curl -s -X POST localhost:8000/api/v1/auth/login \
  -d 'username=dev&password=devpassword' | jq -r .access_token)

# 3 — submit a generation job and read back the job_id
curl -s -X POST localhost:8000/api/v1/jobs -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"engine":"mock","prompt":"a paper plane gliding over a neon city at dusk"}' | jq -r .id

Poll it with curl -s localhost:8000/api/v1/jobs/<job_id> -H "Authorization: Bearer $TOKEN". Interactive OpenAPI docs live at http://localhost:8000/docs.

---

Architecture

flowchart LR
    Client["Client<br/>(Web console · CLI · your app)"]
    API["FastAPI<br/>/api/v1"]
    Router["Engine Router<br/>(EngineRegistry)"]

    subgraph Engines["6 Engines — one BaseEngine contract"]
        direction TB
        E1["mock<br/>offline · no GPU"]
        E2["minimax_h3"]
        E3["wan"]
        E4["cogvideo"]
        E5["hunyuan"]
        E6["openai_compatible<br/>self-hosted"]
    end

    Queue["Celery Workers<br/>retry · quota · state machine"]
    Store["Storage<br/>PostgreSQL · Redis · object store"]

    Client -->|REST + JWT| API
    API --> Router
    Router --> Engines
    API --> Queue
    Queue --> Engines
    Queue --> Store
    Engines --> Store
    Store --> API

Loading

---

How it compares

HunyuanVideo, Wan and CogVideoX are not competitors — they are what VideoForge orchestrates. They are generation models; VideoForge is the control plane that schedules them. The projects below are the real comparison set.

Project	Positioning	Deployment shape	Multi-tenancy	Engine coverage
VideoForge Studio	Control plane / integrable infrastructure	REST API service + Celery workers, Docker & K8s	Users, JWT auth, per-user quotas, job isolation	6 engines: self-hosted + commercial API, one contract
ComfyUI (★110,000+, 2026-04)	Node-based workflow canvas	Local GUI first	None — single operator	Deep local model graph; no commercial API engines, no queue SLA
Wan2GP (community scale, 2026)	Single-machine WebUI for 6–10 GB VRAM	One box, one user	None	Runs Wan-family models locally; no REST API, no horizontal scaling
OpenMontage (★32k, 2026-05)	Agent-orchestrated finished-video production	App that makes one complete video	Not the goal	Optimizes for a finished cut, not for being embedded as infrastructure
browser-use/video-use (★14k, 2026-05)	Agent driving ffmpeg for post-production	Agent/tool runtime	Not the goal	Post-production only; does not schedule generation engines

Star counts and dates are as observed in 2026-08; treat them as a snapshot, not a live figure.

---

Engine support matrix

All capability values are read from each engine's EngineCapabilities declaration in src/videoforge/engines/.

Engine id	Text-to-video	Image-to-video	Max duration	Resolutions	GPU required
mock	✅	❌	30 s	360p / 480p / 720p / 1080p	No — offline, no API key
minimax_h3	✅	❌	30 s	720p / 1080p	No (remote API, MINIMAX_API_KEY)
wan	✅	✅	10 s	480p / 720p	No (remote API, WAN_API_KEY)
cogvideo	✅	❌	10 s	480p / 720p	No (remote API, COGVIDEO_API_KEY)
hunyuan	✅	❌	10 s	720p	No (remote API, HUNYUAN_API_KEY + secret)
openai_compatible	✅	✅	60 s	360p / 720p / 1080p	Yes, on your endpoint — point it at any self-hosted OpenAI-shaped video endpoint

Enable a subset with VIDEOFORGE_ENGINES=mock,wan. The default is all six; engines without credentials simply report configured: false on GET /api/v1/models/health.

---

Beyond generation

• LLM prompt engineering — topic → structured script with shots, narration and visual prompts; short idea → cinematic English prompt (LLM or an offline rule dictionary).
• Storyboards — one generation job per shot, with a golden-ratio seed chain to keep visual continuity across shots.
• Rule-based evaluation — five metrics (structural integrity, motion plausibility, prompt adherence, resolution fidelity, duration fidelity), weighted into a score with a pass threshold and a persisted Markdown report.
• Three interfaces — REST API, React 18 console, and a Typer/Rich CLI (videoforge generate / script / jobs / models / eval / serve).

---

Configuration

Every setting is an environment variable prefixed VIDEOFORGE_; see .env.example for the full list.

Variable	Purpose	Default
VIDEOFORGE_SECRET_KEY	JWT signing key — required	none
VIDEOFORGE_ENGINES	Comma-separated enabled engines	all six
VIDEOFORGE_DB_URL	SQLAlchemy URL	SQLite file
VIDEOFORGE_CELERY_BROKER_URL	Redis broker; omit to run inline	none
VIDEOFORGE_OUTPUT_DIR	Rendered video output directory	data/outputs
MINIMAX_API_KEY / WAN_API_KEY / COGVIDEO_API_KEY / HUNYUAN_API_KEY	Per-engine credentials	empty

---

Deployment

• Docker Compose — docker compose -f docker/docker-compose.yml up -d brings up PostgreSQL, Redis, the API, the Celery worker and Nginx.
• Kubernetes — manifests for Deployment, Service, HPA, Ingress and PVC live in k8s/.
• Observability — Prometheus metrics and OpenTelemetry SDK wiring are included; liveness/readiness probes at /api/v1/health/live and /api/v1/health/ready.

---

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md and SECURITY.md. Run the suite locally with:

pip install -r requirements-dev.txt && pytest -q

Licensed under Apache-2.0.

⭐ Star History