Image Gen

Image Gen

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

• gpt-image-2 is the default.
• 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:

• gpt-image-2 → references/gpt-image-2.md
• nano-banana → references/nano-banana.md

Tool Params

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",
});

After submission, call the track_progress tool: action=status jobIds=<jobId> to poll, action=wait jobIds=<jobId> to block until terminal.

Rules

• Always provide name with a short descriptive asset name.
• Default to submit-only. If there is no follow-up task, stop after submit and tell the user the job was created.
• 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.