ima2-gen

The installer derives its Node.js floor from package metadata and runs an offline installation check before launching the server.

🌐 Live site: lidge-jun.github.io/ima2-gen · 한국어

📖 Developer docs: Documentation site · 한국어

Read in other languages: 한국어 · 日本語 · 正體中文 · 简体中文

ima2-gen is a local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.

Install globally and generate images and videos through the core registry: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, MiniMax, NovelAI, and registered ComfyUI workflows. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup — now with one-click GPT background transparency (server-verified real alpha), annotation hover feedback, and a full light/dark/system theme.

Quick Start

npm install -g ima2-gen
ima2 setup
ima2 serve

Then open http://localhost:3333.

Docker

docker build -t ima2-gen .
docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen

See docs/DOCKER.md for compose usage, required environment, and limitations.

To generate from the CLI, inspect the live lane catalog and choose explicit image/video defaults once:

ima2 models
ima2 defaults set image oauth/gpt-5.6-luna
ima2 defaults set video grok/grok-imagine-video-1.5
ima2 gen "a clean product photo of a red guitar pedal"
ima2 video "a cat playing piano" --duration 5 --resolution 720p
ima2 video "animate this scene" --ref photo.png --duration 10

ima2 gen and generate-mode ima2 video fail closed with NO_DEFAULT_MODEL until a CLI target is configured, unless that call passes --model <lane>/<model> or an explicit --provider <lane>. This prevents an upgrade from silently switching providers or billing lanes.

If 3333 is already occupied, ima2-gen binds the next available port and writes the actual URL to ~/.ima2/server.json. Use ima2 open or the URL printed in the terminal instead of assuming the port.

Using npx? See docs/NPX_QUICKSTART.md for the npx ima2-gen serve workflow.

One-Click Install (no npm required)

Don't have Node.js or npm? Use the platform install script — it detects your environment, installs Node LTS if needed, then installs ima2-gen.

macOS:

curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash

Windows (PowerShell):

irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex

Linux / WSL:

curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash

Each script checks the package-derived Node.js floor, installs Node LTS through the best available method, installs once, and runs the offline installation check before launching ima2 serve. It does not stop unrelated processes or clear global locks.

Setup

ima2 setup offers four authentication choices:

1. GPT OAuth — login with ChatGPT account (free, images only)
2. Grok OAuth — login with xAI/Grok account (images + video)
3. Both — GPT OAuth + Grok OAuth (full feature access)
4. Web setup — configure everything in the web UI

Video generation requires Grok OAuth (option 2 or 3). Run ima2 grok login separately if you already have GPT OAuth configured and want to add video support; it defaults to the manual-paste flow.

Updating

Stop the running server with Ctrl+C, then: (or from another terminal: ima2 stop)

npm install -g ima2-gen@latest

Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. If an installation fails, inspect the reported npm permissions or stop the specific ima2 process yourself; the installer does not perform broad process cleanup.

What It Does

• Classic mode: generate, edit, reuse the current image, paste references, and continue from history.
• Node mode: branch a good image into multiple directions without losing the original.
• Multimode batches: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
• Video generation: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done. Video frame copy buttons (First/Mid/Last) let you extract and copy keyframes from generated videos.
• Storyboard mode: toggle storyboard mode in the composer to maintain character and scene continuity across sequential frames. Works with both image and video generation — image keyframes are composed for video production, and video clips inherit character/environment lock rules.
• Canvas Mode: zoom, pan, annotate (with hover highlighting), erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions. A one-click GPT transparency button sends the current image through the i2i edit lane and reports honestly whether the result carries real pixel alpha — verified on the server, never trusted from provider metadata.
• Raster-to-vector SVG: trace flat raster art into real SVG paths with ima2 vectorize, from AssetGen/Assets, or from Canvas Export. Canvas labels its older self-contained wrapper as SVG (embedded raster) so it cannot be mistaken for a trace.
• NovelAI dual prompt: when NovelAI is selected, Classic, Home, and the mobile compose sheet show Positive prompt and Undesired content as peer panes; they stack below a 719px composer container. Other providers keep the normal single prompt.
• Prompt Builder backend choice: Settings > Providers can keep Builder routing on Auto or pin a supported text backend and model, and the via <backend> badge shows which backend actually answered.
• Light & dark themes: a token-based light mode with tinted neutrals and AA contrast, switchable between light / dark / system in Settings, with no flash on load.
• Local gallery: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
• Reference images: drag, drop, paste, and attach up to 5 references (images) or up to 7 references (video); large images are compressed before upload.
• Prompt library imports: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
• Mobile shell: use the app bar, compose sheet, and compact settings toggle on smaller screens.
• Observable jobs: active and recent jobs are tracked with safe logs and request IDs.

Agent Skills

ima2-gen ships three packaged skills for AI coding agents. These are Markdown instruction files that agents load to get structured workflows for image/video generation, frontend asset production, and design direction discovery.

ima2 skill ls            # list available skills
ima2 skill front         # print the frontend skill
ima2 skill uiux          # print the design skill
ima2 skill front path    # print file path (for agents)
ima2 skill front --json  # JSON wrapper (for agents)
ima2 skill front refs    # list reference modules (35 files)
ima2 skill front ref motion        # load one reference module
ima2 skill install --dir <path>     # install skills to agent's skill dir
ima2 skill install --tmp            # install to temp dir (fallback)

The Frontend and UI/UX skills are production-grade design engineering guides adapted for the ima2 workflow. They cover typography, color systems, layout discipline, Korean UX patterns, motion choreography, and visual verification, with every asset generation step mapped to ima2 gen, ima2 video, and ima2 multimode commands.

SSE Multiplexing

The web UI uses a single GET /api/events Server-Sent Events connection for all generation progress. Multimode, node, and video requests are submitted as async POST (202 { requestId }) and progress events are multiplexed through a shared event bus. This el