🌐 Live site: lidge-jun.github.io/ima2-gen · 한국어
ima2-gen is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
Run it with npx, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation is also supported when configured.
npx ima2-gen serveThen open http://localhost:3333.
If Codex is not logged in yet:
npx @openai/codex login
npx ima2-gen serveIf 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.
You can also install it globally:
npm install -g ima2-gen
ima2 serveBefore updating a global install on Windows, stop any running ima2 serve
process. If npm reports EBUSY or resource busy or locked, close ima2
terminals, end stale node.exe processes if needed, and retry. If the lock
persists, reboot and run the update before starting ima2 again.
- 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.
- 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.
- Reference images: drag, drop, paste, and attach up to 5 references; 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.
Image generation can run through either the local Codex/ChatGPT OAuth path or a configured OpenAI API key.
provider: "oauth"uses the local Codex OAuth proxy.provider: "api"uses the OpenAI API directly. Standard GPT-5 image models stay on the Responses API path, whilegpt-image-2is sent through the dedicated Images API path.- API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
gpt-image-2exposes extra UI/runtime controls only on that model:background,outputCompression, and arbitraryWIDTHxHEIGHTsizes validated locally before upstream.
If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to gpt-5.4-mini, low reasoning, and 1024x1024 unless the request passes validated model, reasoning, size, or web-search options.
The app defaults to gpt-5.4-mini for fast local iteration. Switch to gpt-5.4 when you want the safest balanced image workflow.
gpt-5.4— recommended balanced choice.gpt-5.4-mini— current default and faster draft model.gpt-5.5— strongest quality option when your Codex CLI/OAuth backend supports it. It may use more quota, expose different tool capabilities, or require updating Codex CLI before it works reliably.
The app also exposes quality (low, medium, high) and moderation (auto, low) controls.
gpt-image-2goes through the OpenAI Images API path, not the Responses image tool path.backgroundsupportsauto,opaque, andtransparent.transparentrequirespngorwebp. The app blockstransparent + jpeglocally before any upstream request.outputCompressionis forwarded only forjpegandwebp;pngnever sends that parameter.- Edit requests do not send
input_fidelityforgpt-image-2, because that field is not accepted on this model path in the current app integration. - Custom sizes are validated locally:
WIDTHxHEIGHT, both sides divisible by16, aspect ratio at most3:1, max edge3840, and app-level pixel cap enforced.
Use Classic when you want one strong result quickly.
- Write a prompt.
- Attach or paste references if needed.
- Pick model, quality, size, format, and moderation.
- Generate one image, or enable multimode to fan out several candidate slots from the same prompt.
- Copy, download, continue from the result, or send it into Canvas Mode.
Use Node mode when you want to explore branches.
Each node keeps its own prompt and result. Root nodes can attach local references; child nodes use the parent image as their source. Completed jobs are matched back to nodes by request ID, so reloads and graph version conflicts can recover finished results.
Use Canvas Mode when a generated image is close but needs targeted cleanup before the next prompt.
- Separate viewport panning from selection so you can move around a zoomed image without accidentally changing annotations.
- Use annotation, eraser, multiselect, grouping, undo/redo, and sticky notes while keeping the original gallery image available.
- Pick background-cleanup seeds, preview the mask, and save the cleanup as a canvas version.
- Detect transparent images and show a checkerboard preview; export with preserved alpha or with a chosen matte color.
- Saved canvas versions stay hidden from Gallery and HistoryStrip, but Canvas Mode can reuse them and attach a canvas version as the next reference.
The prompt library can now be filled from local files, GitHub folders, curated sources, and GPT-image hint packs. Imported prompts are indexed locally so search and ranking work without re-importing the same source every session.
Card News is still dev-only and experimental. It is hidden in the default published runtime unless explicitly enabled for development, and it should not be treated as a stable public feature yet.
The settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.
| Command | Description |
|---|---|
ima2 serve [--dev] |
Start the local web server; --dev enables verbose server diagnostics |
ima2 setup |
Reconfigure saved auth |
ima2 status |
Show config and OAuth status |
ima2 doctor |
Diagnose Node, package, config, and auth |
ima2 open |
Open the web UI |
ima2 reset |
Remove saved config |
These require a running ima2 serve. The CLI covers every server route. The most common ones are below — the full CLI reference lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).
| Command | Description |
|---|---|
ima2 gen <prompt> |
Generate from the CLI |
ima2 edit <file> --prompt <text> |
Edit an existing image |
ima2 multimode <prompt> |
Multi-image SSE generation |
ima2 ls [--session <id>] [--favorites] |
List recent history |
ima2 show <name> [--metadata] |
Reveal a generated asset |
ima2 prompt ls -q <search> |
Search the prompt library |
ima2 inflight ls [--terminal] |
List active and recent jobs (alias of ps) |
ima2 config set <key> <value> |
Write to ~/.ima2/config.json |
ima2 ping |
Health-check the running server |
The server advertises its actual port at ~/.ima2/server.json. If 3333 is busy, the backend falls back to 3334+ and CLI commands follow the advertised URL. Override discovery with --server <url> or IMA2_SERVER=http://localhost:3333.
ima2 gen "poster" --model gpt-5.4 --reasoning-effort high
ima2 edit input.png --prompt "make it rainy" --web-search
ima2 multimode "two cats playing" -n 2
ima2 inflight ls --terminal
ima2 config set imageModels.reasoningEffort highFull reference: docs/CLI.md.
Config priority:
environment variables > ~/.ima2/config.json > built-in defaults
ima2 serve keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.
Use ima2 serve --dev, npm run dev, or IMA2_LOG_LEVEL=debug ima2 serve when you need request IDs, node generation phases, OAuth stream diagnostics, or inflight state transitions. Explicit IMA2_LOG_LEVEL and ~/.ima2/config.json values still override the built-in defaults.
The endpoint list moved to docs/API.md so this README can stay focused on first-run use.
Useful references:
ima2 ping says the server is unreachable
Start ima2 serve, then check ~/.ima2/server.json. You can also run ima2 ping --server http://localhost:3333.
OAuth login does not work
Run npx @openai/codex login, confirm ima2 status, then restart ima2 serve.
fetch failed repeats on a proxy/VPN network
Check that the local OAuth proxy is reachable. On networks that require a proxy, enable your proxy client's TUN/TURN-style mode, then retry npx openai-oauth --port 10531. If it still fails, set HTTP_PROXY and HTTPS_PROXY in the same terminal that runs ima2 serve or openai-oauth.
Images fail with API_KEY_REQUIRED
Set OPENAI_API_KEY or configure an API key before using provider: "api". The default OAuth path still works without an API key.
gpt-image-2 returns model_not_found
Check whether your upstream OPENAI_BASE_URL route really supports gpt-image-2 on the Images API. The app now sends gpt-image-2 directly and no longer requires an extra model-mapping env var.
gpt-image-2 edit requests fail when image is /generated/...
Recent builds accept raw base64, image data URLs, relative /generated/... paths, and same-origin absolute /generated/... URLs for image, mask, and references. If you still see generic upstream rejections, rebuild and restart the server first so the new input resolver is active.
Why does transparent + jpeg fail immediately?
JPEG has no alpha channel. The app rejects this combination locally and asks you to switch to png or webp before it sends anything upstream.
Why is input_fidelity not sent for gpt-image-2 edits?
The current gpt-image-2 edit path in this app uses the dedicated Images API integration, and this route intentionally omits input_fidelity to avoid invalid-model request failures.
A large reference image fails The app compresses large JPEG/PNG references before upload. If a file still fails, convert it to JPEG or PNG at a lower resolution and try again. HEIC/HEIF files are not supported by the browser path.
Old gallery images are missing after updating
Recent versions moved generated images from the installed package folder to ~/.ima2/generated. Run ima2 doctor and see Recover old images.
gpt-5.5 fails but other models work
Update Codex CLI first, then retry. If it still fails, your account or backend route may not expose the same image capability or quota for gpt-5.5 yet; use gpt-5.4 as the stable fallback.
The app opened on a different port
If the requested server port is busy, ima2-gen falls back to the next available port and records it in ~/.ima2/server.json. If the port is unexpectedly 3457, your shell may also have inherited PORT=3457 from another local tool. Run unset PORT or start with IMA2_PORT=3333 ima2 serve.
Port 10531 is already used on Windows
Some Windows security tools, including AnySign4PC.exe, may occupy the default OAuth proxy port. Current builds track the actual fallback OAuth port. If you still need a manual override, start with IMA2_OAUTH_PROXY_PORT=11531 ima2 serve and check ima2 doctor.
The built app does not start when I open build/ directly
build/ is only the emitted artifact directory. Start the real app from the project root with npm run dev, npm run build && npm start, or npx ima2-gen serve instead of treating build/ as the entrypoint.
better-sqlite3 breaks after changing Node.js versions
Rebuild native modules from the project root:
npm rebuild better-sqlite3If that still fails, run npm install again under the target Node.js version.
For more beginner-friendly answers, see the FAQ.
git clone https://github.com/lidge-jun/ima2-gen.git
cd ima2-gen
npm install
npm run dev
npm run typecheck
npm test
npm run buildnpm run dev builds the UI and starts the TypeScript server entry with --watch and verbose server diagnostics. npm run typecheck, npm run build:server, and npm run build:cli verify the TypeScript migration and package emit path. Node mode and Canvas Mode are part of the packaged UI by default.
MIT