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 |

| --- | --- | --- | --- |

| gpt-image-2 | references/gpt-image-2.md | Best text rendering, strongest prompt adherence | 16 |

| nano-banana | references/nano-banana.md | Strongest reference-image fidelity | 14 |

| image-01 | references/image-01.md | MiniMax stills / live style; one subject reference via R2 | 1 |

• 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

// 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).