image-gen

# Image Gen Generate AI images via `submit_image` (configured provider keys only). Prefer one clear still per request unless the user asked for variants. ## Model Selection | Model | Reference | Strengths | Max refs | | --- | --- | --- | --- | | `fal` + `falModel` | [references/fal.md](references/fal.md) | Explicit Fal catalog; see tool schema for per-model limits | Model-specific | | `gpt-image-2` | [references/gpt-image-2.md](references/gpt-image-2.md) | Best text rendering, strongest prompt adherence | 16 | | `nano-banana` | [references/nano-banana.md](references/nano-banana.md) | Strongest reference-image fidelity | 14 | | `image-01` | [references/image-01.md](references/image-01.md) | MiniMax stills / live style; one subject reference via R2 | 1 | | `grok-imagine` | [references/grok-imagine.md](references/grok-imagine.md) | xAI Grok Imagine; text-to-image, ≤4 outputs, 1K/2K | 0 | - If Fal.ai is selected or requested, use `model: "fal"` and the requested `falModel` or saved Fal default from capabilities. Ask if none is selected. Native-provider defaults and controls below do not apply to Fal. - Default: `gpt-image-2` when that key is on. - Reference-heavy → `nano-banana`. - User named MiniMax / only MiniMax image key on → `image-01`. - Respect capabilities: do not call a model whose vendor is not configured. **IMPORTANT:** Before generating, READ the chosen model's reference. ## Tool Params | Param | Values | Default | | ------------------- | ----------------------------------------------------------------------- | ------- | | `aspectRatio` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `4:5`, `5:4`, `21:9` | `16:9` | | `imageSize` | `512px`, `1K`, `2K`, `4K` (model-specific) | `1K` | | `width` / `height` | GPT Image: 512–3840, /16; MiniMax: 512–2048, /8 | — | | `quality` | `low`, `medium`, `high`, `auto` (gpt-image-2 only) | `high` | | `referenceAssetIds` | Array of project asset ids — backend resolves bytes server-side | — | | `name` | Short descriptive asset name shown in the library | — | | `count` | Number of images to generate (1–10; image-01 max 9) | `1` | | `promptOptimizer` | MiniMax `image-01` only — `prompt_optimizer` | `false` | | `seed` | MiniMax `image-01` only | — | | `maskAssetId`, `background`, `moderation`, `inputFidelity` | GPT Image edit/output controls | — | | `outputFormat`, `outputCompression` | GPT Image PNG/JPEG/WebP controls | PNG | ## Defaults - Aspect ratio: **16:9**. If the project composition is not 16:9, ASK the user which aspect ratio they want before generating. - Size: **1K**. ## Ask Before Submit - Never auto-upgrade size. - Only pass `imageSize: "2K"` or `"4K"` when the user explicitly asks. Warn that 2K/4K are EXPERIMENTAL and may be slower. ## Reference Images Use when the user provides source material to edit, blend, or use as visual guidance (e.g. "change the background", "combine these into a poster"). - Pass project asset ids via `referenceAssetIds`. The backend fetches and encodes them server-side — never pull the asset bytes yourself. - When the user @-references an image asset, pass its id directly in `referenceAssetIds`. - Formats accepted by backend: png, jpeg, webp, svg (auto-rasterized to png), heic, heif. Each ≤ 50MB. ## Run ```ts // Basic generation submit_image({ model: "gpt-image-2", prompt: "a cute orange cat", name: "Cat", }); // With quality (gpt-image-2 only) submit_image({ model: "gpt-image-2", prompt: "hero poster with bold title", quality: "high", name: "Hero Poster", }); // With reference images — pass project asset ids; backend resolves bytes submit_image({ model: "gpt-image-2", prompt: "change background to beach", referenceAssetIds: ["<assetId>"], name: "Beach Edit", }); // Reference-heavy with nano-banana submit_image({ model: "nano-banana", prompt: "composite poster", referenceAssetIds: ["<id1>", "<id2>"], name: "Composite", }); // Multiple images submit_image({ model: "gpt-image-2", prompt: "product shots", count: 3, name: "Product", }); // MiniMax (optional single subject reference; R2 must be configured for refs) submit_image({ model: "image-01", prompt: "matte product bottle on marble, soft studio light", name: "Bottle still", promptOptimizer: false, }); ``` OpenChatCut’s `submit_image` may return completed pool assets synchronously depending on the provider path. If a `jobId` is returned, use `track_progress`; otherwise treat the asset ids in the result as done. ## Rules - Always provide `name` with a short descriptive asset name. - Before submitting, briefly tell the user what you're about to generate — especially when generating multiple images. - Only call models whose vendor key is configured (capabilities prompt).