ima2

# ima2 Skill Use this skill when an agent needs to operate `ima2-gen` from an installed package or local checkout. Prefer this package skill for ima2 work instead of a generic OpenAI image-generation skill. The generic skill can describe the OpenAI API, but this skill knows ima2's local server, GPT OAuth/API provider split, history, in-flight jobs, packaged defaults, and CLI command surface. **Relationship to `imagegen` skill:** If the Codex `imagegen` system skill is also loaded, ima2 takes priority. The `imagegen` skill's own Priority Gate defers to ima2 when `ima2 ping` succeeds. Do not use both in the same generation task. ## First Commands Start by discovering the local package and running server state: ```bash ima2 skill ima2 skill --json ima2 skill ls # list all skills (core, front, uiux) ima2 skill install --dir <path> # install skills to agent's skill directory ima2 skill install --tmp # install to temp dir (ephemeral fallback) ima2 skill front refs # list frontend reference modules ima2 skill front ref motion # load one reference module ima2 capabilities --json ima2 models --json ima2 defaults --json ima2 ping ``` If the server is not running: ```bash ima2 start # background; or 'ima2 serve' to keep it in this terminal ima2 open ``` Check or control the running server with `ima2 status --runtime --json` (pid, url, launcher: foreground / background / service / desktop; exit 0 running, 3 not running, 1 unknown), `ima2 stop --json`, `ima2 restart` and `ima2 logs -n 50`. A server started by the login service needs `ima2 stop --service`; a server started by the desktop app is restarted from the app. Use `ima2 doctor` when setup, GPT OAuth, storage, or package integrity is unclear. Update a global install with `ima2 update --check` (report only) or `ima2 update --yes` (install, restart the service or background server, verify the new version). Add `--json` for one machine-readable result. It refuses source checkouts and npx runs. ## Generate Images List ready image lanes, choose a persistent CLI target, then generate: ```bash ima2 models --kind image ima2 defaults set image oauth/gpt-6-luna ima2 gen "a clean product photo of a red guitar pedal" ``` Bare `ima2 gen` fails closed when no CLI image target is configured. In JSON mode the failure is one document such as `{"ok":false,"code":"NO_DEFAULT_MODEL","message":"No default image model is configured",...}` and exits 2. Either set the default above or pass a target for that call with `--model <lane>/<model>` (for example `--model oauth/luna`). Never rely on an implicit provider; `--provider auto` was removed. Use high quality when output fidelity matters: ```bash ima2 gen "a print-ready poster" --model oauth/luna --quality high ``` Use direct mode when the prompt should be passed with minimal rewriting: ```bash ima2 gen "exact prompt text" --model oauth/luna --mode direct ``` **`--mode` explained:** - `auto` (default): the server may augment, restructure, or enrich the prompt before sending it to the image model. Good for casual or short prompts. - `direct`: the prompt is passed as-is with minimal server-side rewriting. Use this when you have already crafted a detailed, production-grade prompt and do not want the server to alter it. Use request-level overrides only for that one call: ```bash ima2 gen "cinematic mountain" --model oauth/gpt-5.5 --reasoning-effort high ``` Use Grok when the request should run through the stored xAI OAuth session, mandatory xAI Web Search, planner pass (default: `grok-4.3`), and xAI Images API: ```bash ima2 grok login ima2 grok status ima2 gen "cinematic neon city" --model grok/grok-imagine-image-quality ``` `ima2 grok login` defaults to the manual-paste flow. Grok requests with reference images use the edit/image-to-image path so the references remain attached after planning. Keep Grok references to three total input images. ## NovelAI Image Generation Discover the live NovelAI lane before choosing a model: ```bash ima2 models --kind image --lane nai --json ima2 defaults set image nai/nai-diffusion-5-full ``` The four exact model IDs are: - `nai-diffusion-5-full` - `nai-diffusion-5-curated` - `nai-diffusion-4-5-full` - `nai-diffusion-4-5-curated` Use a persistent NovelAI token from Settings > API Keys or `NOVELAI_API_KEY`. NovelAI does not publish one mandatory token prefix, so never reject a token based on a guessed prefix. Check the lane state through `ima2 models` instead. The same NovelAI options work on `ima2 gen`, `ima2 multimode`, and `ima2 node generate`. Run `ima2 gen --help` for the live enum/range list. Example: ```bash ima2 gen "1girl, blue hair, city at night" \ --provider nai --model nai-diffusion-5-full \ --nai-negative-prompt "lowres, watermark" \ --nai-steps 28 --nai-scale 5 \ --nai-auto-smea --nai-decrisper --nai-variety-plus ``` In the web app, selecting NovelAI changes the composer into two peer panes: **Positive prompt** and **Undesired content**. They sit side by side when the composer is wide enough and stack below a 719px container width. Other providers keep the normal single prompt because they do not share NovelAI's dedicated negative-prompt contract. For V5 native alpha, pair the request flag with an alpha-aware prompt: ```bash ima2 gen "character sprite, transparent background, has alpha" \ --model nai/nai-diffusion-5-full \ --nai-straight-alpha -o sprite.png ``` Supported request controls include sampler, noise schedule, steps, guidance, CFG rescale, seed, undesired-content/UC preset, quality preset, Auto SMEA, Decrisper, Variety+, and V5 native alpha. `--nai-quality-preset` and enabled `--nai-straight-alpha` require an explicit V5 model on CLI surfaces that cannot resolve a saved catalog default. `multimode` and `node generate` require an explicit NovelAI provider or model whenever NAI-native flags are used; `gen` can use a persisted NovelAI CLI default. NovelAI V5 officially supports English and Japanese prompts. Natural language and tags both work; quote text that should appear in the image, and use tags such as `transparent background`, `has alpha`, or `alpha transparency` with the alpha flag. Other languages may work but are not the officially supported prompt pair. Do not assume a generation costs no Anlas. Check the current account and usage limit. The no-Anlas Opus conditions include one image, no base or source image, a normal resolution up to 1024x1024, and at most 28 steps; V5 usage limits can still apply. The ima2 NovelAI lane is text-to-image only. NovelAI itself has additional product features, but ima2 does not currently expose reference/img2img, masks/inpainting, Character Positioning, Director Reference, Vibe Transfer, or Max Enhance. References, edits, and masks fail closed with `NAI_REF_UNSUPPORTED`, `NAI_EDIT_UNSUPPORTED`, or `NAI_MASK_UNSUPPORTED` rather than being dropped. Primary product references, checked 2026-08-27: the official [NovelAI V5 release](https://journal.novelai.net/image-generation-novelai-diffusion-v5-is-here-c2df7c6b8d2d/) and [NovelAI subscription documentation](https://docs.novelai.net/en/subscription/). Native control details come from the official [sampling](https://docs.novelai.net/en/image/sampling/), [steps and guidance](https://docs.novelai.net/en/image/stepsguidance/), [quality tags](https://docs.novelai.net/en/image/qualitytags/), and [seed](https://docs.novelai.net/en/image/seed/) pages, checked the same date. ## Prompt Builder The right-sidebar Prompt Builder refines prompts without generating an image. Open Settings > Providers > Prompt Builder backend to choose where its text request runs, and use Builder model to select a model from that backend's catalog. `Auto` is the default: it tries GPT OAuth, Grok, OpenAI API, then Grok API and selects the first ready backend. Each successful reply carries a `via <backend>` badge showing the backend that actually answered. Choose an explicit backend when cost, credentials, or model behavior must be stable. An unavailable explicit backend returns a typed error and never falls back. Only Auto performs readiness fallback, and there is no retry on a different backend after an upstream request has been sent. The CLI wrapper accepts the same per-request selection: ```bash ima2 prompt build \ --message "Turn this rough idea into a production image prompt" \ --backend <auto|oauth|api|grok|grok-api> \ --model <model> ``` Run `ima2 config get promptBuilder.backend` and `ima2 config get promptBuilder.model` to inspect the persisted server preference. The Builder's model choices depend on the selected backend; do not assume the GPT model list applies to Grok. ## Prompting Guidance GPT Image 2 can follow detailed visual instructions and can render visible text inside images, including labels, signs, posters, UI copy, speech bubbles, and product packaging text. Do not avoid text just because older image models were weak at it. When visible text matters, write the exact words in the target language and script: - Good: `A Korean poster with the exact headline "오늘 공연" and subtext "입장 무료".` - Bad: `A Korean poster with some Korean text.` Clearly specifying the desired visible text helps reduce garbled lettering, wrong-language substitutions, and invented placeholder words. For dense or important text, specify: - exact text; - language and script; - placement; - approximate size; - visual style; - whether extra readable text is forbidden. OpenAI's prompting guide additionally recommends: put literal text **in quotes or ALL CAPS**, state typography (font style, size, color, placement) as explicit constraints, and for exact copy demand it verbatim. The strongest official pattern is a dedicated text block: ```text Poster headline (EXACT, verbatim, no extra characters): "Fresh and clean" Typography: bold sans-serif, high contrast, centered, clean kerning. Ensure the text appears once and is perfectly legible. ``` For tricky words such as brand names or uncommon spellings, spell them out letter-by-letter to improve character accuracy. Use `medium` or `high` quality whenever the image contains small text, dense panels, or multiple fonts. When localizing an existing image, translate the visible text verbatim, add no new words, and preserve everything else — layout, imagery, hierarchy — without reflowing the design. GPT Image 2 can generate both stylized and realistic outputs. State the style directly, for example: - `manga panel` - `webtoon style` - `children's book illustration` - `photorealistic product photo` - `realistic poster mockup` - `cinematic real-world scene` Text rendering is improved, but it is still not a typesetting engine. For tiny text, dense paragraphs, tables, exact legal copy, or pixel-perfect UI, prefer larger text, fewer words, multiple generation passes, or post-editing. ## Agent Image Prompt Protocol When an AI agent authors image prompts, the prompt MUST be **exhaustively detailed**. Vague one-liners produce generic, unusable output. Write every prompt as if you are briefing a senior photographer or illustrator who cannot ask follow-up questions. When using `--mode auto`, the server augments short prompts, but a detailed prompt still produces far better results than relying on auto-augmentation alone. For production assets, prefer `--mode direct` with a fully-specified prompt. ### Structured Prompt Contract Detailed is not enough — the prompt must be **structured**. OpenAI's official gpt-image prompting guide recommends composing prompts in a consistent field order — **scene/background → subject → key details → constraints** — and using labeled segments or line breaks instead of one long paragraph for complex requests. OpenAI's own showcase prompts use labeled blocks such as `Context`, `Characters`, and `Composition`. Apply these rules to every agent-authored prompt: - **Write labeled sections, not a wall of prose.** Long prompts are fine; an unstructured long prompt is not — it becomes impossible to iterate on. - **Order fields by priority.** Scene-first is the official default; lead with the subject when identity or product fidelity dominates. Field order is a priority signal to the model, not a fixed syntax. - **Bind attributes locally.** Keep each object's color, material, pose, count, and position in the same sentence as the object, and state spatial relationships explicitly (foreground/background, left/right, behind, facing, closest to camera). - **Every sentence must change pixels.** State aspect intent, exact hex colors, and transparent background needs directly; cut decorative filler words that describe nothing visible. - **Do not wrap prompts in JSON.** Structured fields are an authoring tool; render them as labeled natural-language sections. Vendors that support JSON prompts (e.g. FLUX) document that JSON and prose are understood equally well — JSON buys automation, not quality. ### Required Spec Fields Every agent-authored prompt MUST include all applicable fields. Omit a field only when it genuinely does not apply (e.g. no text in the image). ```text Use case: <slug: photorealistic-natural | product-mockup | ui-mockup | infographic-diagram | scientific-educational | ads-marketing | productivity-visual | logo-brand | illustration-story | stylized-concept | historical-scene> Asset type: <where the asset will be used: hero, OG image, card, avatar, icon, texture, game sprite, etc.> Primary request: <one clear sentence describing the desired image> Scene/backdrop: <specific environment — not "nice background"> Subject: <main subject with identifying details: material, color, shape, posture, expression> Style/medium: <exact style: editorial photography, flat illustration, 3D render, watercolor, etc.> Composition/framing: <camera angle, crop, subject placement, negative space intent> Lighting/mood: <light source, direction, color temperature, mood, time of day> Color palette: <specific hex codes or named palette — not "modern colors"> Materials/textures: <surface details: matte plastic, brushed steel, linen, weathered wood, etc.> Text (verbatim): "<exact text to render>" with font style, size, color, placement Constraints: <must-keep invariants> Avoid: <explicit negative constraints> ``` ### Specificity Rules | Bad (vague) | Good (specific) | |---|---| | "a nice hero image" | "wide landscape product shot of a matte black thermos on a wet granite countertop, soft morning window light from the left, shallow depth of field, warm neutral tones, negative space on the right for headline overlay" | | "modern background" | "soft radial gradient from #f8f9fa center to #e9ecef edges, subtle paper grain texture at 3% opacity, no objects, no patterns" | | "Korean food photo" | "overhead flat-lay of budae-jjigae in a black stone pot, surrounded by small banchan dishes on a dark wood table, steam visible, warm tungsten lighting, editorial food photography style" | | "logo on white" | "centered geometric mark: two interlocking triangles forming a hexagonal negative space, flat #1a1a2e on #ffffff, no gradients, strong silhouette at 32px, generous padding" | | "a dashboard screenshot" | "realistic SaaS dashboard UI: top nav with avatar, left sidebar with 6 nav items, main area showing a line chart (3 series, 12 months) and a 4-column data table with 8 rows, light theme, Inter font, compact density" | ### Prompt Anti-Patterns These patterns are documented failure modes; reject them when authoring or reviewing prompts: | Anti-pattern | Why it fails | Do instead | |---|---|---| | Keyword soup (`beautiful, stunning, 8k, trending`) | Comma-separated tag piles are a documented anti-pattern for natural-language image models | Structured narrative sentences: subject + attributes + relations | | Unmotivated quality tokens (`masterpiece`, `8K`, `ultra-detailed`) | OpenAI's guide: lens, framing, and lighting language is more reliable for realism than generic quality tokens | Name the look: `shallow depth of field`, `soft window light from the left`, `editorial photography` | | Trusting precision specs (`85mm f/1.2`, `5600K`) | Official guidance: detailed camera specs may be interpreted loosely — they are look cues, not optical simulation | Prefer perceptual terms: `medium close-up`, `eye level`, `warm tungsten mood`; keep mm/Kelvin only as style hints | | Contradictory constraints (`minimalist` + 12 required objects) | Conflicting demands make the model silently drop some of them | Resolve conflicts before generating; one intent per field | | Rewriting everything each iteration | Loses working invariants, causes drift | Change ONE variable per pass, restate invariants | **Negative constraints are model-specific.** For GPT Image, write exclusions as plain prose inside the prompt — `No extra text, no logos, no watermark` — this is the officially recommended form; there is no separate negative-prompt parameter. Do not copy diffusion-style negative lists (`wall, frame`) into GPT Image prompts; that syntax belongs to models with a dedicated negative field (e.g. Imagen), where instruction words like "no/don't" are in turn discouraged. ### Quality and Size Selection | Asset Purpose | Quality | Size | Notes | |---|---|---|---| | Quick draft / iteration | `low` | `1024x1024` | Fastest; square | | Final hero / product shot | `high` | `1536x1024` landscape, `1024x1536` portrait | Or target aspect ratio | | OG / social card | `high` | `1200x640` | Nearest 16px multiple of 1200x630 | | Mobile hero | `high` | `1024x1536` | Portrait | | Print / 4K | `high` | `3840x2160` or `2160x3840` | Max gpt-image-2 supports | | Texture / tile | `medium` | `1024x1024` | Square, seamless edges | | Icon / avatar | `medium` | `512x512` or `256x256` | Small canvas | | Game environment concept | `high` | `1792x1024` or `2048x1152` | Wide cinematic | | Storyboard (for i2v) | `high` | `1024x1024` | 3x3 grid, square | ### Cutout Assets and Background Strategy GPT Image 2 CAN produce true transparent (alpha) backgrounds. Prefer `--bg transparent` for cutout assets: ```bash ima2 gen "a minimal geometric fox head logo mark, flat vector style" \ --bg transparent --quality high --mode direct -o logo.png ``` This asks for a real alpha channel instead of a matte you have to key out later. Verified on the live OAuth path 2026-08-21: 5/5 generations returned RGBA PNGs with all four corners at alpha 0 and 42-56% fully transparent pixels, including genuine PARTIAL alpha on glass and leaf veins. Saved as PNG; JPEG is refused because it cannot carry alpha. Mechanics worth knowing: ChatGPT-session models pin the image tool to the `gpt-image-2-codex` variant, which rejects a FORCED `background: "transparent"` with a 400. ima2 therefore sends `background: "auto"` and puts the cutout intent in the prompt, which is what actually produces the alpha. You do not need to hand-write that suffix — `--bg transparent` adds it. **Use the solid-background-then-remove strategy only when you need a matte** (chroma keying a video, compositing pipelines that expect green screen), or when a specific generation refuses to isolate the subject cleanly: **Generate on a pure solid background:** - **Black** (`#000000`) for reflective/metallic/glass subjects - **White** (`#ffffff`) for dark/matte/opaque subjects - **Brand color** when the target page background is known State the exact hex and ban AI additions: "PURE SOLID BLACK background hex #000000. No checkerboard, no transparency pattern, no gradient, no floor plane,