chatgpt-imagegen

name chatgpt-imagegen version 0.23.6 description Generate new raster images and looping GIF/WebP animations with the user's ChatGPT subscription through the local one-file chatgpt-imagegen CLI, without an API key or daemon. Use for photos, illustrations, icons, hero banners, mockups, sprites, concept art, animation loops, and figures for documents, proposals, blog posts, or READMEs; save outputs in the workspace. Auto mode prefers the logged-in ChatGPT browser through chrome-use to avoid Codex usage and falls back to the Codex backend only when the web path is unavailable. Users with a Gemini subscription can name --backend gemini or agy instead. Proactively propose useful figures while authoring long-form content. Do not use for editing existing images, SVG/vector work, code-native graphics, established icon systems, explicit high-quality or transparent API output, or end-user image-generation services. chatgpt-imagegen — agent skill A standalone Python CLI that produces images via the user's ChatGPT subscription. No API key, no network service, no extra config. It has two OpenAI backends that hit different usage buckets — pick with --backend — plus two opt-in Google/Gemini backends for users who also have a Gemini subscription. Backends Backend Surface Usage bucket Needs Speed web Drives the user's logged-in ChatGPT browser (via chrome-use , formerly agent-browser-stealth ; older installs expose the same binary as agent-browser / abs ) and generates in a regular chat — the same surface as typing in the app. Its real-Chrome connect is what clears Cloudflare + the sentinel proof-of-work a plain/headless client can't. ChatGPT conversation — does not consume the metered Codex-usage limit. Works on any account, including free tier (subject to its daily image cap). chrome-use installed and its extension connected to a Chrome signed in to chatgpt.com . ~30–60 s; each run's chat is filed under a ChatGPT Project (default imagegen , auto-created) instead of littering the history. codex Headless POST to chatgpt.com/backend-api/codex/responses with the image_generation tool, reusing ~/.codex/auth.json . Codex-usage (metered — this is the bucket the user usually wants to spare). codex login (writes ~/.codex/auth.json ). Fast; no browser, no history. Default is auto ( --backend auto , or CHATGPT_IMAGEGEN_BACKEND ): it tries web first because that spares the Codex-usage limit, and falls back to codex only when web is unavailable — i.e. chrome-use isn't installed, the browser isn't reachable, or chatgpt.com isn't logged in. The two not-set-up cases are handled explicitly: Browser not logged in / chrome-use missing → auto silently falls back to codex (a one-line notice prints to stderr). If codex is also not set up, it exits naming both fixes. codex not logged in ( ~/.codex/auth.json absent) → auto still uses web; codex is only the fallback. Auto does not fall back to codex if web was reachable but the generation itself failed after submitting — that would spend the very bucket auto-mode protects. In that case it errors and tells you to rerun with --backend codex if you want the Codex-usage path. Force a single backend with --backend web or --backend codex . Gemini backends (opt-in — auto never picks them) For users who also have a Google/Gemini subscription. Both drive a Google account, not OpenAI. Backend Surface Needs Speed gemini Drives a logged-in gemini.google.com browser via chrome-use — the browser analogue of web . chrome-use , plus a Chrome profile signed in to a subscribed Google account. ~11–24 s agy The Antigravity CLI ( agy ) run headless — the analogue of codex . agy on PATH. Passes --dangerously-skip-permissions by default because headless agy cannot prompt for tool permissions; --no-agy-yolo opts out if the user maintains their own permissions.allow rules. ~14–25 s Their quotas are separate — measured, not assumed: agy returned "Image generation model quota ( gemini-3.1-flash-image ) has been exhausted (429)" while a --backend gemini run on the same Google account succeeded seconds later. So each is a genuine fallback for the other, and a quota error from one names the other in its message. Neither is ever chosen by auto . Deliberate: they hit a different vendor and account, and their output differs in ways a caller would notice. Ask for them by name. Behaviour worth knowing before recommending one: Visible watermark. gemini text-to-image results carry the Gemini "sparkle" glyph, fixed at 65 px in from the bottom-right corner (measured identical across 5 runs at 1024×559). Image-to-image results do not. agy results have no visible mark. Both are watermarked invisibly regardless. agy output carries a Google-signed C2PA manifest whose own description reads "Applied imperceptible SynthID watermark" . The SynthID signal is in the pixels and survives any re-encode. gemini keeps the C2PA manifest on current chrome-use. Gemini renders results from a blob: src, which in-page fetch() still cannot read; chrome-use download-url now resolves the blob inside the page and writes the original bytes to disk, so the signed manifest survives. Older chrome-use rejected blob: outright, leaving only a canvas re-encode — that path is still the fallback and still strips metadata, and the run prints a note naming the upgrade when it has to take it. agy copies the file, so its manifest always survives. --size controls the aspect ratio on gemini , not the pixel count. The chat surface has no size widget, so the ratio is requested in words — and honoured: asking square returned 1024×1024, asking 3:2 returned 1024×687, asking 2:3 returned 687×1024. What you cannot pin is the absolute resolution. With nothing requested Gemini defaults to 16:9, so the backend always asks for something (square when --size is auto ). Real dimensions land in the run meta. The dedicated image model is selected automatically. Before generating, the backend switches the composer to Gemini's image tool, which reports "generated using Nano Banana 2" — otherwise the prompt is answered by whatever chat model is active (seen: Flash-Lite). Best-effort: if the menu moved, the run continues on the chat default rather than failing. --no-gemini-image-tool skips the attempt. It does not remove the watermark or change the default ratio — both were checked against it directly. Pin the profile. Nearly every Chrome profile is signed in to some Google account, and the cookie says nothing about which one holds the subscription — a probe run landed on an account whose "Google AI Pro subscription has expired" page has no composer at all. Set --gemini-profile / CHATGPT_IMAGEGEN_GEMINI_PROFILE . doctor warns when nothing is pinned. Prerequisites For the default web backend: the user must have chrome-use (formerly agent-browser-stealth ; older installs expose the same binary as agent-browser / abs ) and its extension connected to a Chrome that is signed in to chatgpt.com. chrome-use specifically is required — its real-logged-in-Chrome connect is what passes Cloudflare's bot-detection; a plain headless driver will not. The "Temporary Chat" mode disables image generation, so this backend always opens a regular chat. Install policy — never install chrome-use for the user If chrome-use is not installed , do not install it on your own initiative: Generate anyway via the codex fallback (auto mode does this by itself) — the task comes first. Add a single gentle tip to your reply, e.g.: "提示：装上 chrome-use 后，出图会走你已登录的 ChatGPT 浏览器，不消耗 Codex 额度。想配的话我可以一步步带你装好（含浏览器插件）。" — and stop there. Only when the user explicitly says yes , walk them through the guided setup below, step by step, verifying each step before the next. Guided setup (opt-in only): # 1. Install the CLI (no npm, no token — provides `chrome-use`) curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh # 2. Register the native-messaging host chrome-use extension install # 3. Add the Chrome extension, then restart Chrome: # https://chromewebstore.google.com/detail/agent-browser-stealth/knfcmbamhjmaonkfnjhldjedeobeafmk # 4. Sign in to https://chatgpt.com in that Chrome # 5. Verify: a quick `chatgpt-imagegen "test" --backend web` should print "using current Chrome (relay)" Repo: https://github.com/leeguooooo/chrome-use The chrome-use skill ( chrome-use skills get core ) covers the extension-connect flow in depth. For the codex backend: the user must have run, once, ever : npm i -g @openai/codex codex login # opens browser to sign in to ChatGPT That writes ~/.codex/auth.json , which the codex backend reads. No OPENAI_API_KEY is required for either backend — and setting one will not help. This is the subscription path, not the API path. When to use The user asks for a new photo, illustration, icon, hero banner, sprite, cover image, infographic, product mockup, concept art, or any other bitmap deliverable for the current project. The user is happy with subscription-tier quality ( medium quality, no native transparent backgrounds — see Limits below). The deliverable is intended to be saved into the repo or build inputs. You're authoring long-form or explanatory content — a blog post, technical proposal, design doc, tutorial, postmortem, or README — and a figure would help a concept land. You don't need to be asked : propose the figures and generate them (see Illustrating documents below). When not to use The user wants an SVG icon that matches an in-repo vector set — edit those instead. The task is better solved with code (HTML/CSS, canvas, Mermaid, PlantUML). The user wants an existing image modified in place — retouching, cropping, text/logo removal, upscaling, background knock-out. This skill always renders a new image; it cannot return an edited copy of the original's pixels. (Passing an image as a reference with --ref / --style-ref / --composition-ref is supported and encouraged — that's re-generation guided by the image, not editing it.) The user explicitly needs true quality=high or background=transparent — the subscription path caps quality at medium and rejects transparent. Tell the user to use the official /v1/images/generations API with their OPENAI_API_KEY for those cases. The deliverable will be served to end users (e.g. a public service generating images for visitors) — that violates OpenAI's ToS for personal subscriptions. Refuse and explain. How to invoke "<skill-dir>/chatgpt-imagegen" "<prompt>" [options] Call the script by its absolute path next to this SKILL.md — that's the most reliable way and never depends on $PATH . If your agent harness exposes a variable pointing to the skill's install directory, use it; otherwise expand the path you read this file from. First: self-heal a missing CLI npx skills add copies only the markdown — it often does not drop the chatgpt-imagegen script next to this file. So before the first run, check that the CLI exists and fetch it if absent. It's a single self-contained, pure-stdlib Python file (no pip , no deps), so the heal is one curl : CLI= "<skill-dir>/chatgpt-imagegen" # same directory as this SKILL.md if [ ! -x " $CLI " ]; then curl -fsSL https://raw.githubusercontent.com/leeguooooo/chatgpt-imagegen/main/chatgpt-imagegen -o " $CLI " \ && chmod +x " $CLI " fi " $CLI " --version # confirm it runs (needs python3 ≥ 3.10 on PATH) Do this silently — don't ask the user. If the curl fails (offline/proxy), fall back to git clone https://github.com/leeguooooo/chatgpt-imagegen and run chatgpt-imagegen/chatgpt-imagegen , or tell the user to install it standalone (see README). Only python3 is required to run it. If the user has separately put chatgpt-imagegen on $PATH (Option B in the README), you can also just run chatgpt-imagegen "<prompt>" directly and skip the self-heal. Useful flags: Flag When to use --backend auto | web | codex | gemini | agy auto (default) prefers web and falls back to codex only when the browser is unavailable/not-logged-in; web forces the logged-in-browser path (spares Codex-usage); codex forces the headless path (bills Codex-usage); gemini and agy use a Google account instead and are never picked by auto (see Gemini backends ). Also settable via CHATGPT_IMAGEGEN_BACKEND . --gemini-profile NAME ( gemini backend) Chrome profile to drive, overriding --profile . Worth setting — auto-detection cannot tell which Google account holds the subscription. Also CHATGPT_IMAGEGEN_GEMINI_PROFILE . --no-gemini-image-tool ( gemini backend) skip switching the composer to the dedicated image model (Nano Banana 2). Rarely wanted — the switch is already best-effort. --no-agy-yolo ( agy backend) don't pass --dangerously-skip-permissions . Only use it if the user has their own permissions.allow rules — otherwise every headless run fails. --profile auto | relay | NAME (web) Which Chrome profile to drive. auto (default): use the open Chrome if it's logged in, else auto-switch to a profile that is (detected offline from the cookie DB, read-only). relay : only the open Chrome. "Profile 3" : that profile. Note: logged in ≠ able to generate — a free-tier account can still hit its daily image cap. --session NAME (web) Reuse a named Chrome tab group across runs instead of imagegen-<pid> . --project NAME (web) ChatGPT Project to file the run's conversation under — matched by exact name, created automatically if absent , reused if present. Default imagegen (or CHATGPT_IMAGEGEN_PROJECT ). Pass --project "" for a plain top-level chat. If the project step fails, the run warns and continues in a plain chat — it never blocks generation. --keep-tab (web) Leave the ChatGPT tab open after generating (default closes it). Useful for debugging. Implies --keep-conversation . --keep-conversation (web) Keep the ChatGPT conversation after generating. Default deletes it ( PATCH is_visible:false ) so the run leaves no history — it's filed under the project only transiently. Also CHATGPT_IMAGEGEN_KEEP_CONVERSATION=1 . -o PATH Always use when you know where the file should go in the repo. --size 1024x1024 Square icons / logos (verified) --size 1536x1024 Landscape hero banners, social cards (verified) --size 1024x1536 Portrait covers, mobile splashes (verified) --size 3840x2160 or similar 4K landscape (forwarded as-is; backend may reject — fall back to a smaller verified size on failure) --format webp Smaller files for web assets --style NAME Apply a saved asset (a style snippet and/or pinned reference images). Repeatable — stack a character + a style, e.g. --style mascot --style watercolor . See Styles & assets . Overrides any active default set for this run. --no-style Skip all assets (text and pinned refs) for this run even if the user set an active default. --quiet Use in agent contexts so stdout is only the saved path. Progress still streams to stderr (use --no-progress to silence it). --no-progress Fully silence the stderr progress timeline (errors still print). --timeout SECONDS Total wall-clock budget (default 300). Large/detailed images can take 2–3 min — raise it if you see a timed out error. --stall-timeout SECONDS Max silence (no data from backend) before declaring a stall (default 120, clamped to --timeout ). Lower it to fail faster on a hung backend; 0 disables the idle check and waits out the full --timeout . -V , --version Print the CLI version and exit. Run chatgpt-imagegen --version to confirm which build is installed. Looping animations Use chatgpt-imagegen animate "<motion prompt>" for a fixed-camera eight-frame loop. It generates one 4×2 sprite sheet, crops it deterministically, checks for obvious subject drift, and defaults to animated WebP. Add --also-gif for both formats, or --animation-format gif for GIF only. The source sprite is kept beside the output; --keep-frames also preserves all eight cropped PNGs. Animation post-processing is optional and does not affect normal image generation. It requires magick (ImageMagick); WebP additionally requires img2webp (libwebp). Run chatgpt-imagegen doctor before a live animation to see whether these tools and the generation backends are ready. The script prints just the saved path on stdout in every mode; the readable progress timeline and any errors go to stderr , so OUT=$(chatgpt-imagegen "..." --quiet) captures only the path while you still see the timeline. Each timeline line is stamped with elapsed seconds ( [ 12.3s] generating ), so a slow run is legible and a stall is obvious. Styles & assets An asset is a named, reusable look stored in ~/.config/chatgpt-imagegen/styles.json (honours $XDG_CONFIG_HOME ). Each asset carries a text snippet and/or pinned reference images , plus a kind : --kind style (default) — a visual aesthetic (line, palette, texture). Its refs tell the model "match this style, don't copy the content." --kind character — a recurring subject (a mascot, a persona). Its refs tell the model "reproduce this character faithfully as the subject."