> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  Requirements:

  1. Configure the API key for the agent's reasoning model.
  2. Configure the image-generation model name (`MODEL_IMAGE_NAME`).
</Warning>

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

<Note>
  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.
</Note>

`config.yaml` keys:

```yaml title="config.yaml" lines theme={null}
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

```python title="examples/tools/image_generate/agent.py" lines theme={null}
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

<Note>
  `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.
</Note>

## 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:

```python lines theme={null}
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.