On this page

Image generation

GenerateImage lets Holon agents create images from text prompts using a configured image-generation model. The runtime saves generated images to agent_home/media/generated and returns confirmed absolute paths.

What GenerateImage does

When an agent calls GenerateImage, the runtime:

Validates the prompt and parameters — ensures the prompt is non-empty and any optional parameters use supported values.
Routes to an image-generation model — uses the configured image_generation.default provider/model, or auto-discovers the first configured turn model that supports image_generation.
Saves the image — writes the generated image bytes under agent_home/media/generated with a unique filename.
Records durable metadata — computes SHA-256, detects dimensions and MIME type, and returns an absolute path.

Parameters

Tool schema reference: For the complete machine-readable tool schema, input constraints, and return fields, see the Model tool schema inventory and Tools spec.

Parameter	Required	Description
`prompt`	yes	Detailed image-generation prompt
`model`	no	Explicit route ref (`provider@endpoint/model`) for this call
`size`	no	One of `1024x1024`, `1536x1024`, or `1024x1536`
`aspect_ratio`	no	Native aspect ratio (e.g., `1:1`, `3:2`); do not combine with `size`
`resolution`	no	Native resolution (e.g., `1k`, `2k`); do not combine with `size`
`background`	no	One of `auto`, `transparent`, or `opaque`
`output_format`	no	One of `png`, `jpeg`, or `webp`
`name`	no	Filename stem for the saved image

Supported sizes

Size	Ratio	Typical use
`1024x1024`	1:1	Square images, icons, social media posts
`1536x1024`	3:2	Landscape, banners, hero images
`1024x1536`	2:3	Portrait, posters, mobile screens

What GenerateImage returns

Each generated image includes durable metadata:

Field	Description
`id`	Stable reference ID (e.g., `img_abc123`)
`uri`	Absolute path for use in markdown and agent messages
`mime`	Media type (e.g., `image/png`)
`byte_count`	File size in bytes
`sha256`	Content hash
`size`	Image dimensions (width × height) when detectable
`created_at`	Generation timestamp

The result also includes provider/model provenance and the original prompt.

Image routing

Explicit configuration

Set a dedicated image-generation model:

holon config set image_generation.default "openai/gpt-image-2"

When image_generation.default is configured, GenerateImage uses that model for all image generation requests. Use a model route ref that includes the endpoint for unambiguous routing:

holon config set image_generation.default "volcengine@image-openai/doubao-seedream-5.0-lite"

Per-call route selection

Agents can specify model (e.g., "volcengine@image-openai/doubao-seedream-5.0-lite") to select an exact endpoint route for a single call. Explicit per-call selection never falls back and does not alter global configuration.

Auto-discovery

If image_generation.default is not set, the runtime selects the first configured turn model that advertises image_generation capability. This lets agents generate images without dedicated image-generation configuration when the active conversation model supports it.

Fallback provider

When a model does not natively support image generation, GenerateImage falls back to the first configured image-generation enabled model. This is transparent to the agent.

Supported providers

Image generation is supported through providers whose models advertise the image_generation capability:

Provider	Model	Notes
OpenAI	gpt-image-2	Native image generation
Volcengine	doubao-seedream-5.0-lite	Via Volcengine Ark plan endpoint
xAI	grok-imagine-image-2.0	Grok Imagine via the xAI OpenAI-compatible Images API

See Models reference for the current list of image-generation capable models.

Volcengine Seedream setup

To use Volcengine's Seedream model for image generation, configure a dedicated plan endpoint:

holon config set providers.volcengine.endpoints.image-openai.transport openai_chat_completions
holon config set providers.volcengine.endpoints.image-openai.base_url "https://ark.cn-beijing.volces.com/api/plan/v3"
holon config set providers.volcengine.plans.image-openai.endpoint image-openai

Then set the image generation default:

holon config set image_generation.default "volcengine@image-openai/doubao-seedream-5.0-lite"

xAI Grok Imagine setup

xAI Grok Imagine image models are exposed through the xAI OpenAI-compatible Images API and are selected explicitly, because they are image-only models and are not conversation turn candidates:

holon config set image_generation.default "xai@grok-imagine-image-2.0"

Supported models include grok-imagine-image, grok-imagine-image-2.0, and grok-imagine-image-quality. The xai provider resolves XAI_API_KEY or the Holon-managed xAI OAuth profile.

xAI does not accept OpenAI's size, background, or output_format request fields. size is mapped to the closest aspect_ratio at 1k (1024x1024 -> 1:1, 1536x1024 -> 3:2, 1024x1536 -> 2:3). background and output_format are rejected with a clear error instead of being silently ignored. The runtime records the media type xAI reports, so the saved file extension matches the image bytes.

Output management

Generated images are saved under agent_home/media/generated/ with timestamped filenames. When a name is provided, the filename uses that stem; otherwise it defaults to generated_<timestamp>. Image delivery enforces bounded decoding limits: 32 MiB source and output sizes, 8,192 pixels per edge, 16,777,216 total pixels, and 192 MiB decoder allocation limits. If conversion fails, the original downloaded image is retained on disk for local recovery.

The returned absolute path can be used in agent markdown output for in-conversation rendering. Images are accessible through the Web GUI file browser and workspace file API.

When agents use GenerateImage

Agents call GenerateImage when a task involves visual creation:

Data visualization — generate charts, diagrams, or infographics from data descriptions.
UI mockups — create visual representations of interface concepts.
Logo and icon design — generate branding assets or icons.
Illustration — create visual aids for documentation or presentations.

The tool is part of the LocalEnvironment capability family and is available to every agent by default.

CLI verification

GenerateImage is a model-facing tool; it is not directly callable from the CLI. Agents use it through the normal tool-calling mechanism. The image generation model routing can be inspected with:

holon config get image_generation.default