ManimGenAI 0.1.0

Generate Manim videos from natural-language prompts using OpenAI Responses API.

ManimGenAI

Turn natural-language prompts into rendered Manim videos using OpenAI.

ManimGenAI is designed to work in two modes:

• as a CLI tool for quickly generating videos from prompts
• as a Python API that another script, agent, or AI system can call programmatically

The core pipeline is:

prompt + optional local assets
-> structured video plan
-> Manim Python code
-> AST validation
-> render
-> automatic repair loop on failure
-> final MP4

ManimGenAI is designed to be agent-friendly: it can be used as a tool inside larger AI systems.

Highlights

• Uses the OpenAI Responses API instead of legacy chat completions. (Other providers soon)
• Separates planning, code generation, and repair into distinct stages with custom AI pipelines.
• Renders through python -m manim render, so it does not rely on manim being globally available in PATH.
• Stores (by default) full execution artifacts for each run: prompt, plan, generated code, validation output, logs, and render errors.
• Exposes both a CLI and an importable Python API.
• Supports local assets like images, SVGs, fonts, and simple data files.

Status

This project is already functional end-to-end:

• package structure in place
• CLI and Python API implemented
• OpenAI planning/codegen/repair client implemented
• real local Manim render path verified
• unit tests passing

Current defaults are optimized by stage:

• best -> gpt-5.4 across planner, codegen, and repair
• balanced -> gpt-5.4 for planner and gpt-5.4-mini for codegen and repair
• fast -> gpt-5.4-mini across the pipeline

Installation

Base install

python -m pip install -e .

Development extras

python -m pip install -e .[dev]

Optional packaging extras

python -m pip install -e .[packaging]

Requirements

You need:

• Python 3.11+
• Manim installed in the environment you will use
• FFmpeg available on the machine
• an OpenAI API key

Configuration

Copy .env.example to .env and fill in the values you want.

Minimal setup:

OPENAI_API_KEY=your_key_here
MANIMGENAI_MODEL_PLANNER_BALANCED=gpt-5.4
MANIMGENAI_MODEL_CODEGEN_BALANCED=gpt-5.4-mini
MANIMGENAI_MODEL_REPAIR_BALANCED=gpt-5.4-mini

Important defaults:

• balanced is the recommended everyday profile.
• model fallback is disabled by default.
• artifacts are kept by default.
• final videos are written to artifacts/output unless you override the output directory.

CLI Usage

Render a video from a prompt

manimgenai render "Create a 10-second elegant animation explaining the dot product with vectors and projection." --quality balanced --output-name dot_product

Render from a prompt file

manimgenai render --prompt-file prompt.txt --quality balanced --output-name lesson_01

Use local assets

manimgenai render \
  "Animate this SVG logo and turn it into a graph scene" \
  --asset assets/logo.svg \
  --asset assets/chart.png \
  --output-name branded_scene

Open the final video automatically

manimgenai render "Explain eigenvectors visually" --open

Emit machine-readable JSON

manimgenai render "Explain the unit circle" --json

Inspect environment health

manimgenai doctor

Show prompt templates

manimgenai prompt-template --style pro
manimgenai prompt-template --style short
manimgenai prompt-template --system all

Build an optional Windows executable

manimgenai build-exe --name manimgenai

Python API

from manimgenai import RenderRequest, render_video

request = RenderRequest(
    prompt="Explain the chain rule with a clean educational style.",
    output_name="chain_rule",
)

result = render_video(request)
print(result.status)
print(result.video_path)

How Prompting Works

ManimGenAI uses two prompt layers.

1. Internal system prompts

These are built into the tool:

• planner: transforms the free-form request into a structured video plan
• coder: turns the plan into one Manim Python module
• repair: fixes failed generations using validation messages or traceback output

You can inspect them with:

manimgenai prompt-template --system all

2. User prompt

This is the prompt you send to the tool. Better prompt structure usually gives better videos.

Recommended high-quality template:

Goal:
Audience:
Core concept or story:
Visual style and mood:
Approx duration in seconds:
Aspect ratio or output format:
Camera movement notes:
Objects, graphs, formulas, or text that must appear:
Scene progression beat by beat:
Assets to use (optional):
Non-negotiable constraints:
Things to avoid:

Compact version:

Goal:
Audience:
Visual style:
Approx duration:
Camera or motion:
Important elements to show:
Things to avoid:
Assets to use (optional):

Safety Model

Generated code is validated before execution.

By default, ManimGenAI blocks dangerous imports and calls such as:

• subprocess
• socket
• requests
• httpx
• eval
• exec
• open

Unsafe mode can be enabled explicitly, but the intended default is safe generation.

Artifacts

Each run stores a full artifact bundle under:

<output_dir>/_artifacts/<timestamp>-<job-name>/

That folder includes:

• the original prompt
• the structured plan JSON
• each generated code attempt
• validation results
• render error messages
• Manim logs

This makes debugging and prompt iteration much easier.

Project Structure

manimgenai/
  cli.py
  config.py
  schemas.py
  prompts.py
  client.py
  planner.py
  codegen.py
  validator.py
  renderer.py
  pipeline.py
  doctor.py
tests/
main.py
pyproject.toml
README.md

Testing

Run unit tests:

python -m pytest

Run integration tests that render with local Manim:

python -m pytest -m integration

Example Outputs

manimgenai doctor

Example:

Python: C:\Users\you\anaconda3\python.exe
[OK] openai: openai 1.108.1
[OK] manim: manim 0.19.0
[OK] ffmpeg: C:\Program Files\ffmpeg\bin\ffmpeg.exe
[OK] manim_cli: Manim Community v0.19.0
[OK] openai_api_key: configured

manimgenai render "..."

Human-readable example:

Video generated: artifacts\output\trigonometry_demo.mp4
Scene: UnitCircleTrigonometryScene
Artifacts: artifacts\output\_artifacts\20260410-163616-trigonometry_demo

manimgenai render "..." --json

Machine-readable example:

{
  "status": "success",
  "video_path": "artifacts\\output\\trigonometry_demo.mp4",
  "scene_name": "UnitCircleTrigonometryScene",
  "attempt_count": 1,
  "artifacts_dir": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo",
  "generated_code_path": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo\\attempts\\attempt-1.py",
  "logs_path": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo\\logs\\attempt-1_UnitCircleTrigonometryScene.log",
  "errors": [],
  "timings": {
    "planning_seconds": 11.94,
    "initial_codegen_seconds": 107.86,
    "render_attempt_1_seconds": 17.26
  }
}

manimgenai prompt-template --system all

Example:

{
  "planner": "...system prompt for structured planning...",
  "coder": "...system prompt for Manim code generation...",
  "repair": "...system prompt for fixing validation or render failures..."
}

Notes

• The current implementation is already usable, but it can still be improved in prompt tuning and UTF-8 handling.

Disclaimer

ManimGenAI uses AI models to generate video plans and Python code.

While the system includes validation and safety checks, the generated content may:

• contain inaccuracies or conceptual mistakes
• produce inefficient, unexpected, or non-idiomatic code
• fail to render correctly
• include unintended behaviors due to model limitations

Executing AI-generated code may lead to unexpected side effects depending on the environment.

All generated outputs should be reviewed before execution and before being used in production, educational material, or public-facing content.

The user is responsible for verifying the correctness, safety, and appropriateness of any generated video or code, as well as any consequences derived from executing it.

ManimGenAI does not guarantee correctness, reliability, or fitness for a particular purpose.

License

MIT