foundry-image-gen

name	foundry-image-gen
description	Generate or edit images with GPT-Image-2 in Azure AI Foundry via the generate_image tool. Triggers: generate image, edit image, reference image, create image, make an image, draw, illustrate, diagram, visual, mockup, logo, concept art.
license	MIT
allowed-tools	generate_image, Bash, PowerShell

Foundry Image Generation

This plugin provides the generate_image tool for text-to-image generation and reference-image edits backed by GPT-Image-2 deployed in Azure AI Foundry.

Prerequisites

• Azure CLI installed and authenticated (az login)
• Cognitive Services OpenAI User role on the target Azure OpenAI account (the normal RBAC role for token-based inference)
• A GPT-Image-2 model deployed in Azure AI Foundry (GlobalStandard SKU)

The extension pins its Entra token to the resource's subscription (FOUNDRY_IMAGE_SUBSCRIPTION), so it works even when your default az context is a different subscription/tenant. Without this, a wrong-tenant token returns 500: Unable to get resource information.

Configuration

Defaults target the maintainer's Foundry resource. To point at your own deployment, set any of these env vars (each falls back to the built-in default) — no code edits or per-machine file changes needed:

Env var	Default	Description
FOUNDRY_IMAGE_ENDPOINT	https://foundry-eg6typ.openai.azure.com	Azure OpenAI account endpoint URL
FOUNDRY_IMAGE_DEPLOYMENT	gpt-image-2	Model deployment name
FOUNDRY_IMAGE_API_VERSION	preview	Images API version
FOUNDRY_IMAGE_SUBSCRIPTION	maintainer's sub ID	Subscription GUID that owns the resource (pins the token tenant)

Usage

The generate_image tool accepts:

Parameter	Required	Description
prompt	Yes	Detailed description of the image to generate
size	No	1024x1024 (default), 1536x1024, 1024x1536, or auto
quality	No	low, medium, or high (default)
reference_images	No	Array of 1-5 local PNG/JPEG paths under 50 MB each. When present, the tool uses the image edits API
input_fidelity	No	low or high; defaults to high for reference-image edits
filename	No	Output filename without extension (default: generated-image)

Images are saved as PNG to the session's files/ directory, or to a temp directory ($TEMP/foundry-images) when no session workspace is available.

Operating Playbook

Before generating, show the user the prompt, reference strategy, and variant count unless they explicitly delegate independent iteration.

• For a simple scene or up to five references, generate in one pass.
• For more than five identities or an exact roster, make clean labeled reference sheets in groups of five or fewer, generate panels, visually review every panel, retry only failed panels, then integrate with up to four accepted panels plus one master roster or layout board.
• Keep prompts compact and positive. Express identity through accessories, markings, proportions, and expression.
• Use input_fidelity: high to preserve identity, layout, or accepted panels. Use low if references overcopy logos, photographic framing, or overly human anatomy.
• When randomness matters, generate up to three separately named variants. Make calls sequentially and allow for the 2 RPM quota.

Recovery

• Missing subjects or generic characters: simplify the composition, strengthen distinct identity cues, or split into reviewed panels.
• Over-copied references: lower input fidelity and restate the desired composition positively.
• Bad text: shorten it, use a clean layout reference, or regenerate only the failed panel.
• Moderation block: simplify neutral wording; never attempt to bypass safety controls.
• 429 response: wait for the built-in retry or quota window before another sequential call.
• Special conceptual characters: define a concrete silhouette, material, scale, placement, and expression instead of relying on an abstract label.

Visual Quality Gate

Open or render every candidate. Check subject count and order, spelling, anatomy, identity cues, special characters, unwanted source text or logos, and requested dimensions. An HTTP success or saved file is not completion.

Run the focused reference-image regression check with:

node plugins/foundry-image-gen/.github/extensions/foundry-image-gen/extension.mjs --self-test

Rate Limits

GPT-Image-2 GlobalStandard deployments have low default quotas (2 RPM). If you hit 429 errors, request a quota increase via the Azure portal.