Image generation

Overview

Tool identifier image_generate. image_generate generates images from text. For image-to-image editing, see image_edit. Import path: from veadk.tools.builtin_tools.image_generate import image_generate

Environment & prerequisites

Requirements:

Configure the API key for the agent’s reasoning model.
Configure the image-generation model name (MODEL_IMAGE_NAME).

Environment variables:

MODEL_IMAGE_API_KEY: API key for the image-generation model; falls back to MODEL_AGENT_API_KEY and then to model.api_key from the config file when unset
MODEL_AGENT_API_KEY: API key for the agent’s reasoning model
MODEL_IMAGE_NAME: image-generation model name
MODEL_IMAGE_API_BASE: image-generation model API endpoint; defaults to the ModelArk endpoint

Credentials are resolved at tool execution time, not at import time. Importing the tool module does not initialize a client or require credentials to be present.

config.yaml keys:

config.yaml

model:
  image:
    name: doubao-seedream-5-0-260128
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here

For BytePlus, explicitly configure the media model name, API base URL, and key for your enabled service. Do not assume CLOUD_PROVIDER overrides media configuration. Capabilities and parameter limits depend on the selected model service. MODEL_IMAGE_API_BASE is read at import time; configure it before starting the process.

Usage

examples/tools/image_generate/agent.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_generate import image_generate

agent = Agent(
    name="image_generate_agent",
    model_name="doubao-seed-2-1-pro-260628",
    description="Generate images on demand.",
    instruction="You are an image-generation expert. Call image_generate to create images for the user.",
    tools=[image_generate],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("Generate a cute kitten")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

Notes

image_generate is the canonical import name. from veadk.tools.builtin_tools.generate_image import image_generate still works, but the generate_image module is deprecated — use image_generate instead.

Parameters and results

Parameter	Type	Default	Description
`tasks`	`list[dict]`	Required	Image request list
`tool_context`	`ToolContext`	Injected	Invocation context used to store generated results
`timeout`	`int`	`600`	Timeout in seconds for each image request
`model_name`	`str \| None`	`None`	Per-call model override; otherwise uses `MODEL_IMAGE_NAME` or the built-in default

Each task supports these fields. Omitted optional request fields use model-service defaults. Set dimensions or watermark behavior explicitly when they matter.

Field	Type	Default	Description
`task_type`	`str`	Required	Intent: `text_to_single`, `text_to_group`, `single_image_to_single`, `single_image_to_group`, `multi_image_to_single`, or `multi_image_to_group`
`prompt`	`str`	Required	Image description; specify the requested count for groups
`image`	`str \| list[str]`	Omitted	Reference image URLs or Base64; omit for text-only generation
`size`	`str`	Service default	Supported resolution level or dimensions such as `2048x2048`
`response_format`	`str`	Service default	`url` or `b64_json`; usually use `url`
`watermark`	`bool`	Service default	Add a watermark
`sequential_image_generation`	`str`	Service default	Set `auto` for groups, or `disabled` for one image
`max_images`	`int`	Service default	Upper bound used only with `auto`, not an exact count
`tools`	`list[dict]`	Omitted	Supported models accept `[{"type": "web_search"}]` for text-only generation
`output_format`	`str`	Service default	`png` or `jpeg` on models supporting this field

Generation mode follows image and sequential_image_generation; task_type alone does not fill the other fields. This request explicitly allows up to three images:

tasks = [{
    "task_type": "text_to_group",
    "prompt": "Generate 3 illustrations of a cat, each in a different pose",
    "size": "2048x2048",
    "response_format": "url",
    "sequential_image_generation": "auto",
    "max_images": 3,
    "watermark": True,
}]

Results contain status, success_list, error_list, and error_detail_list. Each success item maps an image name to a URL. A batch may partly succeed, so inspect error lists as well. With b64_json, the tool attempts to upload the image to TOS and return a URL, requiring writable object storage configuration; it does not return raw Base64 unchanged as the final tool result.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Overview

Environment & prerequisites

Usage

Notes

Parameters and results

​Overview

​Environment & prerequisites

​Usage

​Notes

​Parameters and results

Overview

Environment & prerequisites

Usage

Notes

Parameters and results