ima2-gen

🌐 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 from eight core lanes: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, and MiniMax. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup.

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 for nvm/fnm/brew/winget, installs Node LTS through the best available method, and handles stale process cleanup automatically.

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:

npm install -g ima2-gen@latest

Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. On older versions (< 1.1.22) or if you see EBUSY on Windows, use the install script which handles stale process cleanup automatically.

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, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
• 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 eliminates the browser 6-connection limit that previously caused gallery hangs during concurrent generation. CLI clients that do not send async: true still receive per-request SSE streams for backward compatibility.

Provider Paths

Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, the bundled Grok provider, or the Gemini provider via Antigravity CLI.

• provider: "oauth" uses the local Codex OAuth proxy.
• provider: "api" calls the OpenAI Responses API with the hosted image_generation tool.
• provider: "grok" starts bundled progrok on 127.0.0.1:18645, runs mandatory xAI Web Search plus a planner pass (default: grok-4.5, configurable in settings or via --planner-model), then calls xAI Images API through the local proxy. grok-4.3 remains available as an explicit compatibility override.
• provider: "grok-api" calls the xAI Images API directly with XAI_API_KEY (no bundled progrok OAuth proxy).
• provider: "agy" spawns the Antigravity CLI (agy -p) to generate images via Google Gemini's default_api:generate_image tool (model: nano-banana-2). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
• provider: "gemini-api" calls the Google Generative Language API directly. Supports two models: nano-banana-2 (Gemini 3.1 Flash Image) and nano-banana-pro (Gemini 3 Pro Image). Auth is via GEMINI_API_KEY env var, web UI key management, or a Vertex AI service account JSON (VERTEX_SERVICE_ACCOUNT_JSON). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the response_format field. Per-model cost differs: `nano-