generate_image

Generate or edit images and write generated image files to temporary paths.

Source

Field	Type	Required	Description
`subject`	`string`	Yes	Main image prompt. For edits, describe the desired result and each input image's role.
`action`	`string`	No	What the subject is doing.
`scene`	`string`	No	Location or environment.
`composition`	`string`	No	Camera angle and framing.
`lighting`	`string`	No	Lighting setup.
`style`	`string`	No	Artistic style.
`text`	`string`	No	Text to render in the image. Keep short and specify legibility when needed.
`changes`	`string[]`	No	Edit instructions for input images.
`aspect_ratio`	`"1:1" \| "3:4" \| "4:3" \| "9:16" \| "16:9" \| "3:2" \| "2:3"`	No	Requested output aspect ratio.
`image_size`	`"1024x1024" \| "1536x1024" \| "1024x1536"`	No	Requested output size where the selected provider supports it.
`input`	`Array<{ path?: string; data?: string; mime_type?: string }>`	No	Input images by local path or inline base64 data.

Success with image data:
- content[0].type = "text"
- content[0].text summarizes provider/model and saved image paths.
- details = { provider, model, imageCount, imagePaths, images, responseText?, revisedPrompt?, promptFeedback?, usage? }
Provider responses with no image data return imageCount: 0, empty imagePaths / images, and any provider text/feedback available.

The SDK injects generate_image as a custom tool via getImageGenTools().
execute(...) resolves credentials and provider from the active model registry / session credentials.
Input images are resolved from path relative to the session cwd or from inline data + mime_type.
The tool validates provider-specific aspect_ratio support.
Provider dispatch:
- OpenAI / OpenAI Codex: hosted Responses image-generation path with WebP output.
- Antigravity: Google Antigravity SSE endpoint.
- OpenRouter: OpenRouter image-capable chat completion path.
- xAI: Grok image endpoint.
- Gemini: Gemini generateContent with responseModalities: ["IMAGE"].
Inline images from the provider response are saved to temporary files; paths and inline image metadata are returned.

Text-to-image: provide subject and optional style/composition fields, no input.
Image edit: provide one or more input images plus changes and a subject that identifies each image role.
Text rendering: use text; the prompt instructs callers to request sharp, legible, correctly spelled short text.

Filesystem: reads local input images and writes generated output images to temp paths.
Network: sends prompts and optional images to the selected image provider.
Session state: reads active model, session id, cwd, credentials, settings, and optional injected fetch.
Background work / cancellation: provider calls use the caller abort signal combined with a 3 minute timeout.

Local input images are capped at 35 * 1024 * 1024 bytes (MAX_IMAGE_SIZE).
Provider timeout is 3 * 60 * 1000 ms.
OpenAI output format is WebP.
Common aspect ratios are 1:1, 3:4, 4:3, 9:16, and 16:9; xAI also accepts 3:2 and 2:3.
image_size schema accepts 1024x1024, 1536x1024, and 1024x1536.

Missing credentials: No image API credentials found...
OpenAI path without an active GPT model: Missing active GPT model for OpenAI image generation.
Antigravity credentials without projectId: Missing projectId in antigravity credentials.
Provider HTTP failures surface as provider-specific error messages with status metadata where available.
Unsupported provider/aspect-ratio combinations fail before the provider request.

The tool is a custom tool, not a built-in AgentTool class, so its root docs live here even though the model-facing prompt is in src/prompts/tools/image-gen.md.
Multiple input images should be named in subject as Image 1, Image 2, etc. so the provider receives unambiguous edit instructions.