# Ima2 > Use the ima2-gen CLI/server to generate, edit, inspect, and manage local AI image generation jobs. - Skill: `lidge-jun/ima2` (Agent Skill) - Install (CLI): `npx skillmds@latest add lidge-jun/ima2` - Raw SKILL.md: https://api.skillmd.com/api/skills/lidge-jun/ima2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: lidge-jun (https://skillmd.com/u/lidge-jun) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lidge-jun/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 # 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 serve ima2 open ``` Use `ima2 doctor` when setup, GPT OAuth, storage, or package integrity is unclear. ## Generate Images List ready image lanes, choose a persistent CLI target, then generate: ```bash ima2 models --kind image ima2 defaults set image oauth/gpt-5.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 /` (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 ` 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 \ --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: Asset type: Primary request: Scene/backdrop: Subject:
Style/medium: Composition/framing: Lighting/mood: Color palette: Materials/textures: Text (verbatim): "" with font style, size, color, placement Constraints: Avoid: ``` ### 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, no shadow, no vignette." Use `--mode direct`. ```bash ima2 gen "3D chrome splash on PURE SOLID BLACK background hex #000000. \ No gradient, no floor, no shadow, no vignette." \ --quality high --size 1024x1024 --mode direct -o splash.png ``` **Remove background after generation:** - CSS `mix-blend-mode: screen` (black bg on light page) - CSS `mix-blend-mode: multiply` (white bg on dark page) - ima2 Canvas Mode background cleanup (export with alpha or matte) - `ima2 edit asset.png --prompt "remove the background, keep only the subject"` - Programmatic: `sharp` / ImageMagick / `rembg` **Anti-pattern:** hand-writing "transparent background" into a prompt WITHOUT `--bg transparent`. Bare prompt wording sometimes yields a checkerboard pattern painted into an opaque image; the flag sends the real API parameter and the tuned suffix together. Always verify alpha rather than trusting the look of a preview: `sharp(file).metadata()` should report `channels: 4, hasAlpha: true`. ### Raster-to-Vector (SVG) `ima2 gen` always produces raster. When you need a REAL vector — a logo that scales, an icon for a design system, a brand-safe SVG asset — trace the raster afterwards. `flat vector style` in a prompt only produces a bitmap that LOOKS vector; it has no paths. ```bash # 1. generate a cutout, 2. trace it ima2 gen "a minimal geometric fox head logo mark, flat vector style" \ --bg transparent --quality high --mode direct -o logo.png ima2 vectorize logo.png -o logo.svg --json ``` Runs fully local — no server, no provider, no network. `--json` reports `pathCount`, `bytes`, and `elapsedMs` so an agent can check the result programmatically. Presets: `auto` (default, best colour fidelity), `flat` (fewer colour layers), `detailed`, and `mono` (binary silhouette). Tune with `--color-precision 1-8`, `--filter-speckle 0-128`, `--corner-threshold 0-180`; pass a knob only when you actually want to override the preset, since any value replaces the tuned config. **Where it works and where it does not.** Measured on a 1254x1254 keyed character asset: `auto` produced 722 paths at 585KB and is visually indistinguishable from the source. Cutouts, icons, logos, flat art, and sprite frames trace cleanly. Photographs and small text do NOT — text becomes illegible smudges and gradients fragment into hundreds of bands. Key or generate a clean cutout FIRST; tracing quality follows input flatness. `mono` has no alpha channel, so a transparent cutout becomes a silhouette on a black field. Use it for stencils and line art, not for cutouts. In the app, the same operation is **Convert to SVG** on an AssetGen tile or Assets library preview. Canvas Mode also exposes **Trace to SVG (vector)** in Export: it flattens the current canvas composition to PNG, saves that hidden canvas version, then opens the same preset and fine-tuning panel. Do not confuse it with **SVG (embedded raster)**, which keeps the base image as bitmap data and vectorizes only Canvas annotations. ### Korean Text in Images When generating images with Korean text: - Write the exact Korean string in quotes: `"오늘의 추천"`, not "some Korean text" - Describe the scene in English and keep only the visible Hangul string in Korean: `A clean summer poster with the exact Korean headline "여름 축제"`. Practitioner testing found all-Korean prompts produced garbled Hangul while English prompts with a quoted Korean string rendered correctly (heuristic, not a guarantee) - Start with short, label-like strings (a headline, a button) before attempting body copy; Hangul glyph complexity makes long dense text the most failure-prone case - Specify font style explicitly: `고딕체 (Gothic/Sans-serif)` or `명조체 (Myeongjo/Serif)` - Specify placement (top-center, bottom-left) and approximate size relative to the canvas - For mixed Korean + English, specify which script appears where and in what hierarchy - After generation, always inspect the result with `view_image` — garbled or substituted Hangul is common and must be caught before use - For critical Korean text, generate 2-4 candidates (`-n 4`) and pick the cleanest render - If a render is right except for the text, do a targeted `ima2 edit` pass that restates the exact string and changes only the text region; if spelling still will not stabilize after a couple of passes, stop retrying - For legally or commercially exact Korean copy (packaging, UI, contracts), the reproducible production path is: generate the image with a reserved empty text area (`no text` in that region), then composite real type with an actual Korean font in an editor or code. Korean text failure is a cross-model limitation, not an ima2-specific one ### Multi-Candidate Strategy For important visual assets (hero images, key illustrations, brand materials), generate multiple candidates and select the best: ```bash # 4 candidates from one prompt ima2 gen "" -n 4 -d ./candidates --quality high # Or multimode for structurally different directions ima2 multimode "" --max-images 4 -d ./candidates ``` After generation, inspect every candidate with `view_image` before selecting. Do not blindly use the first result. ### Prompt Iteration - Start with one high-detail prompt. Inspect the result with `view_image`. - On the next pass, make ONE targeted change and re-specify all constraints. Do not rewrite the entire prompt from scratch. - Repeat invariants every iteration to prevent drift. - This mirrors the official guidance: start from a clean baseline, iterate with small single-variable follow-ups instead of overloading one prompt, and when a detail drifts, restate it explicitly — never assume it persists. - If the model consistently fails on a detail, try rephrasing, breaking the request into a base generation + `ima2 edit` pass, or switching `--mode`. ### Frontend Asset Quick Recipes Copy-paste starters for common frontend assets: **Hero image (landing page):** ```bash ima2 gen "Use case: product-mockup. Asset type: landing page hero. A premium wireless headphone floating at a slight angle against a soft warm-gray studio backdrop. Matte black finish with brushed aluminum accents. Soft three-point studio lighting, key light from upper-left. Shallow depth of field. Wide composition with generous negative space on the right for headline overlay. No text, no logos, no watermark." \ --quality high --size 1536x1024 --mode direct -o hero.png ``` **OG / social share image:** ```bash ima2 gen "Use case: ads-marketing. Asset type: social share card. Clean product flat-lay of a notebook, pen, and ceramic mug on a white marble desk. Overhead shot. Soft diffused daylight. Space in the upper third for title overlay. Warm neutral palette. No text, no logos, no watermark." \ --quality high --size 1200x640 --mode direct -o og-image.png ``` **App screenshot mockup background:** ```bash ima2 gen "Use case: stylized-concept. Asset type: hero background for device mockup. Soft abstract gradient from #f0f4f8 to #dbeafe with subtle geometric shapes at 5% opacity. Clean, modern, minimal. No objects, no patterns, no text." \ --quality medium --size 1920x1088 --mode direct -o mockup-bg.png ``` **Avatar / profile placeholder:** ```bash ima2 gen "Use case: stylized-concept. Asset type: user avatar. Friendly stylized portrait of a young professional, neutral expression, looking slightly left. Flat illustration style with subtle shadows. Solid #e5e7eb background. Circular crop safe. No text." \ --quality medium --size 512x512 --mode direct -o avatar.png ``` **Korean product hero:** ```bash ima2 gen "Use case: product-mockup. Asset type: Korean service landing hero. A modern smartphone at 15-degree tilt showing a clean fintech app UI. The screen displays a balance card with exact text \"잔액 1,234,500원\" in 고딕체, large centered. Soft gradient backdrop from #f8fafc to #e2e8f0. Studio lighting from upper-right. No other text, no logos, no watermark." \ --quality high --size 1536x1024 --mode direct -o korean-hero.png ``` **Game environment concept art:** ```bash ima2 gen "Use case: stylized-concept. Asset type: game environment concept art. A vast underground cavern with bioluminescent fungi on limestone walls. A narrow stone bridge crosses a dark chasm. Volumetric blue-green light from fungi clusters. Cinematic concept art style with industrial realism. Wide-angle, low camera, deep perspective. Mist rising from below. No characters, no text, no watermark." \ --quality high --size 1792x1024 --mode direct -o cave-env.png ``` ## Reference / I2I Workflows Reference generation: ```bash ima2 gen "turn this into a clean product render" --ref input.png --quality high ``` Multimode reference workflow: ```bash ima2 multimode "create four coherent variations" --ref input.png --max-images 4 ``` Node-mode reference workflow: ```bash ima2 node generate "continue this concept" --ref input.png ``` Image edit workflow: ```bash ima2 edit input.png --prompt "make the object blue while preserving composition" ``` Do not use positional edit prompts. `ima2 edit` requires `--prompt`. ### Structured Edit Brief OpenAI's official edit pattern is `"change only X"` + `"keep everything else the same"` — an edit prompt does not need to re-describe the whole final image, but it must make the delta and the invariants explicit. Author every edit prompt as a brief: ```text Desired result: Change only: Preserve exactly: Do not add or remove: ``` "Keep everything else the same" alone is weak — name the fragile properties in the lock list, and repeat the same lock list on every iterative edit pass to prevent drift. **Annotated inputs.** If the edit source or a reference image carries drawn markup (arrows, boxes, circled regions, sticky notes), the model tends to treat the markup as image content and reproduce it. Prefer sending the clean image plus text instructions derived from the markup. When the annotated image must be sent, state before and after the edit list that the markup is temporary editing instructions only — interpret it, apply the edits, then remove every trace of it from the output. **Removal edits.** "Remove X" alone is weak. Pair the removal command with a positive description of what replaces it, then lock the rest: "Remove the sticky note. Show the continuous walnut desk surface where it was, matching the surrounding grain, lighting, and perspective — no residue, outline, or discoloration. Preserve every other object, the framing, and the color grading exactly." For stubborn removals, generate multiple candidates and re-edit only the residual region instead of enlarging the prompt. ### Multi-Reference Rules When passing multiple `--ref` images, label each reference by index and role inside the prompt, then state the relationships explicitly: ```text Image 1: base scene and composition. Image 2: subject identity reference. Image 3: style reference. Place the subject from Image 2 into Image 1. Apply only Image 3's palette and brushwork. Preserve Image 1's framing, background, perspective, and lighting. ``` - Put the most identity-critical reference (face, logo, product) **first**: documented GPT Image behavior preserves the first input with the richest texture and detail. - When several faces must all stay recognizable, combine them into one composed reference image before generating instead of passing many separate portraits. - For compositing, specify the source element, its destination and location, the preserved context, and harmonization: scale, perspective, lighting, shadows. ## Parallel Generation There is no `--parallel` flag. For multiple candidates from the same prompt, prefer one server-side batch request: ```bash ima2 gen "four poster candidates" -n 4 -d ./out --quality high ima2 multimode "four different poster directions" --max-images 4 ``` For truly different prompts, independent CLI jobs can run concurrently against the same server. Capture request IDs with JSON output, then monitor or cancel: ```bash ima2 gen "variation 1" --quality high --json ima2 gen "variation 2" --quality high --json ima2 ps --json ima2 cancel ``` Treat `capabilities.limits.maxParallel` as advisory client-side queue guidance only. It is not a guaranteed server-side semaphore. ## Agent Mode (web UI only) Agent Mode is a conversational image workspace (sessions, turns, a durable per-session queue, slash commands, `/question`). It is served at `/api/agent/*` and lives in the web UI — there is no `ima2 agent` CLI command. From the CLI, drive generation with `ima2 gen`, `ima2 edit`, `ima2 multimode`, and `ima2 node generate` instead. ## Watching Jobs Use JSON when another agent needs to reason about active work: ```bash ima2 inflight ls --json ima2 inflight ls --kind multimode --terminal --json ``` Expect job fields such as `requestId`, `kind`, `phase`, `startedAt`, `prompt`, `model`, and `sessionId`. Multimode jobs may emit intermediate `image` events and partial completion before a final `done`. ## Prompt Import Build a structured image prompt from a message or transcript: ```bash ima2 prompt build --message "make this product prompt clearer" --json ima2 prompt build --messages @conversation.json --json ``` Preview a local markdown/text prompt source before committing: ```bash ima2 prompt import preview ./prompts.md --json ``` Import a JSON export body: ```bash ima2 prompt import json ./prompts-export.json --folder __root__ ``` Import a raw image into history: ```bash ima2 history import ./local-image.png ``` ## Defaults Inspect the running server defaults, including `defaults.cli.image` and `defaults.cli.video` in JSON: ```bash ima2 defaults --json ``` Inspect local effective defaults without contacting a server: ```bash ima2 defaults --local --json ``` Discover live model IDs and lane status before choosing a CLI target: ```bash ima2 models ima2 models --kind image --lane oauth --json ima2 models --kind video --json ``` `ima2 models --json` has the stable shape `{"ok":true,"kinds":{"image":[],"video":[]}}`. It requires the server; an unreachable server returns `SERVER_UNREACHABLE` and exits 3. Persist the server-side model defaults shared by GPT OAuth and API provider paths: The built-in OAuth image default is `gpt-5.6-luna`; Grok image and video code defaults are `grok-imagine-image-quality` and `grok-imagine-video` respectively. For video, set `grok-imagine-video-1.5` as your default and leave the base model for edit and extension, which are the only things 1.5 cannot do. ```bash ima2 defaults set model gpt-5.5 ``` Persist the fail-closed CLI image and video targets separately: ```bash ima2 defaults set image oauth/gpt-5.6-luna ima2 defaults set video grok/grok-imagine-video ima2 defaults reset image ima2 defaults reset video ``` Setting a CLI target validates the live catalog. Unknown models and lanes are rejected, and locked/disconnected/key-missing lanes cannot become defaults. Persist the default reasoning policy: ```bash ima2 defaults set reasoning high ``` Restart a running server after changing persisted defaults: ```bash ima2 serve ``` Request flags such as `--model` and `--reasoning-effort` are per-call overrides. They do not change persistent defaults. ## Capability Values Use `ima2 capabilities --json` as the source of truth for: - supported image models; - unsupported model ids that should not be used as defaults; - valid reasoning efforts; - valid quality values; - valid provider, mode, and moderation values; - writable config keys and their environment-variable overrides; - reference count and image count limits; - package/server version. Use only models from: ```text valid.imageModels.supported ``` Do not pick models from: ```text valid.imageModels.unsupported ``` Discover writable configuration keys: ```bash ima2 config keys --json ``` ## Safety Notes - Do not print API keys, OAuth tokens, config files, or `.env` values. - Use `ima2 capabilities --json` before guessing model names. - Use `ima2 skill path` when an agent needs the installed Markdown skill path. - Use `ima2 skill refs` to discover reference modules for front/uiux skills. - Use `ima2 skill ref ` to load a specific reference module on demand. - Use `ima2 skill install --dir ` to install skills to the agent's skill directory. - Use `ima2 inflight ls --json` or `ima2 ps --json` to inspect active jobs. ## Video Generation Generate AI videos through a configured Grok or MCP lane. Grok OAuth requires a SuperGrok subscription; MCP lanes require their own connected subscription. ### Quick Start ```bash ima2 models --kind video ima2 defaults set video grok/grok-imagine-video-1.5 ima2 video "a cat playing piano" # text-to-video, uses saved default ima2 video "animate this" --ref photo.png # image-to-video: photo is frame 1 ima2 video "same cat, on a beach" --ref cat.png --as-reference # new scene, same subject ima2 video "cinematic" --ref a.png --ref b.png # 2+ refs are always references ``` Targets use `--model /`; a bare ID is accepted only when it is unique across lanes. Generate-mode `video` also accepts an explicit `--provider `; run `ima2 video --help` for the lanes this build supports, since that list is derived from the provider registry rather than written here. `--provider auto` is removed. Runway and Higgsfield are MCP lanes. They submit `POST /api/mcp/generate` (202) and the CLI waits on SSE until completion. MCP generation supports `-n 1` only, and `--ref` values must be generated gallery filenames, not arbitrary local paths. Core-only planning/session flags are rejected with `FLAG_NOT_SUPPORTED`. `ima2 gen` and `ima2 video` also accept `--character ` on MCP lanes: the element must be a `character` element in the assets workspace with a provider binding for the selected lane (Runway: stateless refs + optional `@tag`). Fail-closed envelopes: `CHARACTER_ELEMENT_NOT_FOUND`, `CHARACTER_ELEMENT_AMBIGUOUS`, `CHARACTER_BINDING_MISSING`, `CAPABILITY_MISMATCH` (core lane or model without `image_references`), `BINDING_NOT_READY`, and server-side `CHARACTER_ELEMENT_CONFLICT` / `CHARACTER_REFS_EXCEED_PROVIDER_CAP`. Lane availability is runtime state, so it is not recorded here: a lane can be ready, missing a key, disconnected, or locked, and only a running server knows which. Read it with `ima2 capabilities` (per-lane status with the reason) or `ima2 models --kind video` (per-model rows). When `ima2 capabilities` reports `source: local`, no server answered and it carries no lane state at all — absence there means unknown, not unavailable. `ima2 upscale ` upscales through the MCP media-action pipeline: images take `--scale-factor 2|4|8|16` (above 2 requires `--flavor sublime`), `--flavor`, `--sharpen`, `--smart-grain`, `--ultra-detail`; videos take no parameters. Multishot generation is `POST /api/mcp/multishot` (CLI surface planned). Video edit is the 2-step `edit-video-preview` → `edit-video-submit` media action; stage-1 returns a synchronous keyframe preview. ### Model choice: reach for 1.5 first `grok-imagine-video-1.5` is the model to use unless you are editing or extending an existing video. It owns everything that makes a clip better; the base model owns two operations 1.5 refuses. | Capability | `grok-imagine-video-1.5` | `grok-imagine-video` (base) | |---|---|---| | Reference images (1-7) | yes | yes | | 1080p | yes (not in reference-to-video) | no | | Duration 1-15s | yes | yes | | Preset voices (`--voice`) | yes, up to 3 | **no** — returns 400 | | Video edit (V2V) | **no** — returns 400 | yes | | Video extension | **no** — returns 400 | yes | So: **1.5 for generating, base for editing and extending.** Nothing needs both at once. `grok-imagine-video-1.5-preview` is still accepted as a compatibility alias, but write `grok-imagine-video-1.5` in anything new. Prompt-only text-to-video on 1.5 is implemented as an internal white-canvas image-to-video anchor, because upstream 1.5 rejects raw T2V. That is an implementation detail — ask for text-to-video normally. When a request does fall back to another model, the result carries `requestedModel`, `effectiveModel`, and `modelFallback`. Read `effectiveModel` before naming or reporting which model produced a clip. A request carrying `--voice` never falls back, because the base model cannot honor the voice and silently dropping it would return a clip missing what was asked for. ### Modes (from --ref count, plus your choice at one reference) | Refs | Mode | Max Duration | |------|------|-------------| | 0 | text-to-video | 15s | | 1 | image-to-video (default) | 15s | | 1 + `--as-reference` | reference-to-video | 15s | | 2-14 | reference-to-video | 15s | …(truncated)