[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1742":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":24,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":16,"starSnapshotCount":16,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},1742,"ima2-gen","lidge-jun\u002Fima2-gen","lidge-jun","Minimal CLI + web UI for OpenAI GPT Image 2 generation. Dual auth: API Key (paid) or OAuth via ChatGPT (free). Text-to-image, image-to-image, parallel gen, custom sizes.","https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002F",null,"TypeScript",384,55,167,10,0,14,83,185,42,5.24,false,"main",true,[26,27,28,29,30,31,32,33],"chatgpt","cli","express","gpt-image-2","image-generation","nodejs","oauth","openai","2026-06-12 02:00:32","# ima2-gen\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Flogo.png\" alt=\"ima2-gen logo\" width=\"240\">\n\u003C\u002Fp>\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fima2-gen)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fima2-gen)\n[![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20-brightgreen)](https:\u002F\u002Fnodejs.org\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n\n> 🌐 **Live site**: [lidge-jun.github.io\u002Fima2-gen](https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002F) · [한국어](https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002Fko\u002F)\n>\n> 📖 **Developer docs**: [Documentation site](https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002Fdocs) · [한국어](https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002Fko\u002Fdocs)\n>\n> **Read in other languages**: [한국어](docs\u002FREADME.ko.md) · [日本語](docs\u002FREADME.ja.md) · [简体中文](docs\u002FREADME.zh-CN.md)\n\n`ima2-gen` is a local image generation studio for people who want the ChatGPT\u002FCodex image workflow in a small desktop-like web app.\n\nRun 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.\n\n![ima2-gen classic generation screen with prompt composer, generated image, compact model label, and result metadata.](assets\u002Fscreenshots\u002Fclassic-generate-light.png)\n\n## Quick Start\n\n```bash\nnpx ima2-gen serve\n```\n\nThen open `http:\u002F\u002Flocalhost:3333`.\n\nIf Codex is not logged in yet:\n\n```bash\nnpx @openai\u002Fcodex login\nnpx ima2-gen serve\n```\n\nIf `3333` is already occupied, `ima2-gen` binds the next available port and writes the actual URL to `~\u002F.ima2\u002Fserver.json`. Use `ima2 open` or the URL printed in the terminal instead of assuming the port.\n\nYou can also install it globally:\n\n```bash\nnpm install -g ima2-gen\nima2 serve\n```\n\nBefore updating a global install on Windows, stop any running `ima2 serve`\nprocess. If npm reports `EBUSY` or `resource busy or locked`, close ima2\nterminals, end stale `node.exe` processes if needed, and retry. If the lock\npersists, reboot and run the update before starting ima2 again.\n\n## What It Does\n\n- **Classic mode**: generate, edit, reuse the current image, paste references, and continue from history.\n- **Node mode**: branch a good image into multiple directions without losing the original.\n- **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.\n- **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.\n- **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.\n- **Reference images**: drag, drop, paste, and attach up to 5 references; large images are compressed before upload.\n- **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.\n- **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.\n- **Observable jobs**: active and recent jobs are tracked with safe logs and request IDs.\n\n## Provider Paths\n\nImage generation can run through either the local Codex\u002FChatGPT OAuth path or a configured OpenAI API key.\n\n- `provider: \"oauth\"` uses the local Codex OAuth proxy.\n- `provider: \"api\"` calls the OpenAI Responses API with the hosted `image_generation` tool.\n- API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.\n\nIf no provider is specified, the app keeps the current OAuth\u002Fdefault 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.\n\n![Settings workspace showing OAuth active and API key provider available.](assets\u002Fscreenshots\u002Fsettings-oauth-generation.png)\n\n## Model Guidance\n\nThe app defaults to **`gpt-5.4-mini`** for fast local iteration. Switch to **`gpt-5.4`** when you want the safest balanced image workflow.\n\n- `gpt-5.4` — recommended balanced choice.\n- `gpt-5.4-mini` — current default and faster draft model.\n- `gpt-5.5` — strongest quality option when your Codex CLI\u002FOAuth backend supports it. It may use more quota, expose different tool capabilities, or require updating Codex CLI before it works reliably.\n\nThe app also exposes quality (`low`, `medium`, `high`) and moderation (`auto`, `low`) controls.\n\n## Workflows\n\n### Classic Mode\n\nUse Classic when you want one strong result quickly.\n\n1. Write a prompt.\n2. Attach or paste references if needed.\n3. Pick model, quality, size, format, and moderation.\n4. Generate one image, or enable multimode to fan out several candidate slots from the same prompt.\n5. Copy, download, continue from the result, or send it into Canvas Mode.\n\nFor a control-by-control guide to Prompt Studio, multimode recipes, Direct mode,\nreasoning effort, and gallery favorite behavior, see the\n[Prompt Studio manual](docs\u002FPROMPT_STUDIO.md).\n\n![Multimode sequence with four candidate slots generating from one prompt and active job history in the sidebar.](assets\u002Fscreenshots\u002Fmultimode-sequence.png)\n\n### Node Mode\n\nUse Node mode when you want to explore branches.\n\n![Node mode with connected generated cards and compact per-node metadata.](assets\u002Fscreenshots\u002Fnode-graph-branching.png)\n\nEach 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.\n\n### Canvas Mode\n\nUse Canvas Mode when a generated image is close but needs targeted cleanup before the next prompt.\n\n- Separate viewport panning from selection so you can move around a zoomed image without accidentally changing annotations.\n- Use annotation, eraser, multiselect, grouping, undo\u002Fredo, and sticky notes while keeping the original gallery image available.\n- Pick background-cleanup seeds, preview the mask, and save the cleanup as a canvas version.\n- Detect transparent images and show a checkerboard preview; export with preserved alpha or with a chosen matte color.\n- Saved canvas versions stay hidden from Gallery and HistoryStrip, but Canvas Mode can reuse them and attach a canvas version as the next reference.\n\n![Canvas Mode with zoom controls, annotation marks, a sticky note, and the canvas toolbar.](assets\u002Fscreenshots\u002Fcanvas-mode-cleanup.png)\n\n### Prompt Library And Imports\n\nThe 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.\n\n![Prompt import dialog for bringing prompts into the library, showing GitHub folder controls, curated sources, and searched prompt candidates before import.](assets\u002Fscreenshots\u002Fprompt-import-dialog.png)\n\n### Experimental Card News Mode\n\nCard News is still dev-only and experimental. It is hidden in the default\npublished runtime unless explicitly enabled for development, and it should not\nbe treated as a stable public feature yet.\n\n### Settings\n\nThe settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.\n\n![Settings workspace with account navigation and generation model controls.](assets\u002Fscreenshots\u002Fsettings-workspace.png)\n\n## CLI Commands\n\n### Server\n\n| Command | Description |\n|---|---|\n| `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |\n| `ima2 setup` | Reconfigure saved auth |\n| `ima2 status` | Show config and OAuth status |\n| `ima2 doctor` | Diagnose Node, package, config, and auth |\n| `ima2 doctor image-probe [--json]` | Run sanitized image probes for no-image diagnostics |\n| `ima2 open` | Open the web UI |\n| `ima2 reset` | Remove saved config |\n\n### Client\n\nThese require a running `ima2 serve`. The CLI covers every server route. The most common ones are below — the [full CLI reference](docs\u002FCLI.md) lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).\n\n| Command | Description |\n|---|---|\n| `ima2 gen \u003Cprompt>` | Generate from the CLI |\n| `ima2 edit \u003Cfile> --prompt \u003Ctext>` | Edit an existing image |\n| `ima2 multimode \u003Cprompt>` | Multi-image SSE generation |\n| `ima2 ls [--session \u003Cid>] [--favorites]` | List recent history |\n| `ima2 show \u003Cname> [--metadata]` | Reveal a generated asset |\n| `ima2 prompt ls -q \u003Csearch>` | Search the prompt library |\n| `ima2 inflight ls [--terminal]` | List active and recent jobs (alias of `ps`) |\n| `ima2 config set \u003Ckey> \u003Cvalue>` | Write to `~\u002F.ima2\u002Fconfig.json` |\n| `ima2 ping` | Health-check the running server |\n\nThe server advertises its actual port at `~\u002F.ima2\u002Fserver.json`. If `3333` is busy, the backend falls back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server \u003Curl>` or `IMA2_SERVER=http:\u002F\u002Flocalhost:3333`.\n\n```bash\nima2 gen \"poster\" --model gpt-5.4 --reasoning-effort high\nima2 edit input.png --prompt \"make it rainy\" --web-search\nima2 multimode \"two cats playing\" -n 2\nima2 inflight ls --terminal\nima2 config set imageModels.reasoningEffort high\n```\n\nFull reference: [docs\u002FCLI.md](docs\u002FCLI.md).\n\n## Configuration\n\nConfig priority:\n\n```text\nenvironment variables > ~\u002F.ima2\u002Fconfig.json > built-in defaults\n```\n\n| Variable | Default | Description |\n|---|---:|---|\n| `IMA2_PORT` \u002F `PORT` | `3333` | Web server port |\n| `IMA2_HOST` | `127.0.0.1` | Web server bind host |\n| `IMA2_OAUTH_PROXY_PORT` \u002F `OAUTH_PORT` | `10531` | OAuth proxy port |\n| `IMA2_SERVER` | — | CLI target override |\n| `IMA2_CONFIG_DIR` | `~\u002F.ima2` | Config and SQLite location |\n| `IMA2_ADVERTISE_FILE` | `~\u002F.ima2\u002Fserver.json` | Runtime discovery file |\n| `IMA2_GENERATED_DIR` | `~\u002F.ima2\u002Fgenerated` | Generated image directory |\n| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback image model |\n| `IMA2_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh` |\n| `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |\n| `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |\n| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | Recent terminal job retention for debug views |\n| `OPENAI_API_KEY` | — | API key for the `provider: \"api\"` Responses API image path and auxiliary API-key features |\n| `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Default image model for `provider: \"api\"` |\n| `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: \"api\"` |\n| `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: \"api\"` |\n| `IMA2_API_ALLOW_WEB_SEARCH` | `true` | Toggle web search for `provider: \"api\"` |\n| `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |\n\n### Logging modes\n\n`ima2 serve` keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request\u002Fnode\u002FOAuth structured logs are hidden by default.\n\nUse `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 `~\u002F.ima2\u002Fconfig.json` values still override the built-in defaults.\n\n## API Reference\n\nThe endpoint list moved to [docs\u002FAPI.md](docs\u002FAPI.md) so this README can stay focused on first-run use.\n\nUseful references:\n\n- [Developer documentation site](https:\u002F\u002Flidge-jun.github.io\u002Fima2-gen\u002Fdocs) — Overview, Quickstart, Architecture, Modes, Providers, CLI, Config, and Server API\n- [CLI Reference](docs\u002FCLI.md)\n- [API Reference](docs\u002FAPI.md)\n- [Prompt Studio manual](docs\u002FPROMPT_STUDIO.md)\n- [FAQ](docs\u002FFAQ.md)\n- [Recover old images](docs\u002FRECOVER_OLD_IMAGES.md)\n- [Korean README](docs\u002FREADME.ko.md)\n- [Japanese README](docs\u002FREADME.ja.md)\n- [Chinese README](docs\u002FREADME.zh-CN.md)\n\n## Troubleshooting\n\n**`ima2 ping` says the server is unreachable**\nStart `ima2 serve`, then check `~\u002F.ima2\u002Fserver.json`. You can also run `ima2 ping --server http:\u002F\u002Flocalhost:3333`.\n\n**OAuth login does not work**\nRun `npx @openai\u002Fcodex login`, confirm `ima2 status`, then restart `ima2 serve`.\n\n**`fetch failed` repeats on a proxy\u002FVPN network**\nCheck that the local OAuth proxy is reachable. On networks that require a proxy, enable your proxy client's TUN\u002FTURN-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`. On Windows, also check for auto-start network interception tools, including DNS\u002Ffragmentation bypass tools such as SecretDNS, because they can break OAuth or streaming image responses even when the browser appears connected.\n\n**Images fail with `API_KEY_REQUIRED`**\nSet `OPENAI_API_KEY` or configure an API key before using `provider: \"api\"`. The default OAuth path still works without an API key.\n\n**Image generation returns `EMPTY_RESPONSE` or no image data**\nRun `ima2 doctor image-probe --json > ima2-image-probe.json` and attach the safe JSON when opening an issue. For OAuth cases, also capture `ima2 gen \"고양이\" --no-web-search --json` and `ima2 gen \"고양이\" --json` while `ima2 serve` is running. Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream responses, prompt history, or generated base64. See the [FAQ support bundle](docs\u002FFAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image).\n\n**A large reference image fails**\nThe app compresses large JPEG\u002FPNG references before upload. If a file still fails, convert it to JPEG or PNG at a lower resolution and try again. HEIC\u002FHEIF files are not supported by the browser path.\n\n**Old gallery images are missing after updating**\nRecent versions moved generated images from the installed package folder to `~\u002F.ima2\u002Fgenerated`. Run `ima2 doctor` and see [Recover old images](docs\u002FRECOVER_OLD_IMAGES.md).\n\n**`gpt-5.5` fails but other models work**\nUpdate 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.\n\n**The app opened on a different port**\nIf the requested server port is busy, `ima2-gen` falls back to the next available port and records it in `~\u002F.ima2\u002Fserver.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`.\n\n**Port `10531` is already used on Windows**\nSome 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`.\n\nFor more beginner-friendly answers, see the [FAQ](docs\u002FFAQ.md).\n\n## Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Flidge-jun\u002Fima2-gen.git\ncd ima2-gen\nnpm install\nnpm run dev\nnpm run typecheck\nnpm test\nnpm run build\n```\n\n`npm 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.\n\n## License\n\nMIT\n","ima2-gen 是一个用于生成图像的轻量级CLI和Web UI工具，支持通过OpenAI GPT进行文本到图像、图像到图像的转换。该项目采用TypeScript编写，核心功能包括使用API密钥（付费）或通过ChatGPT的OAuth认证（免费）两种方式进行身份验证，并提供了文本转图像、基于现有图像生成新图像、并行生成以及自定义尺寸等功能。此外，它还具备经典模式、节点模式、多模式批处理、画布模式等高级特性，以满足不同需求。ima2-gen适合需要在本地环境中利用AI技术快速创建或修改图像内容的场景，如创意设计、原型制作和个人项目开发等。",2,"2026-06-11 02:45:44","CREATED_QUERY"]