image-gen

Image Gen

If submit_image is not loaded yet, load it with ToolSearch before calling it, so you use its real parameters instead of guessing.

ChatCut image generation and editing require an active paid Pro subscription and use credits for every model. If submit_image returns FEATURE_NOT_INCLUDED, surface the upgrade requirement; do not retry another ChatCut model to bypass it. Codex native image generation keeps its own host entitlement and is not governed by this ChatCut requirement.

Generate AI images through the backend generation API. Submit-only: creates a generation job and returns a jobId.

After submission, use track_progress tool to check status or wait for completion.

Model Selection

Model	Strengths	Max refs
gpt-image-2.5-flare	Default: fast everyday generation and editing	10
gpt-image-2.5-sunburst	Precision edits and detailed creative work	10
gpt-image-2	Previous GPT image model	10
nano-banana	Strongest reference-image fidelity	14

• gpt-image-2.5-flare is the default. Honor the image model attached to the user prompt or explicitly requested.
• Use gpt-image-2.5-sunburst when the user selects it for precise editing.
• nano-banana is the reference-heavy choice. Use it when reference-image fidelity matters more than text rendering, or when the user needs more than 10 reference images.

IMPORTANT: Before generating, READ the model's reference document for params, limits, and prompt tips:

• Image 2.5 Flare / Sunburst → references/gpt-image-2.5.md
• gpt-image-2 → references/gpt-image-2.md
• nano-banana → references/nano-banana.md

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	1K, 2K, 4K	1K
quality	low, medium, high, auto; Image 2.5 also xhigh, max	high
background	auto, opaque, transparent (Image 2.5 only; PNG output)	auto
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, each becomes a separate job)	1

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 set 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.5-flare",
  prompt: "a cute orange cat",
  name: "Cat",
});

// With quality (OpenAI models)
submit_image({
  model: "gpt-image-2.5-flare",
  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.5-flare",
  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.5-flare",
  prompt: "product shots",
  count: 3,
  name: "Product",
});

After submission, call track_progress with action=status jobIds=<jobId>. If the current task depends on a non-terminal result, call action=wait and do what its result says: where automatic follow-ups are supported it registers one and you end your turn; otherwise it returns sleep-and-recheck guidance. Neither action blocks.

Rules

• Always provide name with a short descriptive asset name.
• Wait for completion unless the user only asked to queue. Use returned asset ids for further edits; use edit_item to place an image on the timeline when requested.
• Generation costs credits. Before submitting, briefly tell the user what you're about to generate — especially when generating multiple images.
• Do not use this skill for job management. Use track_progress tool for that.