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

## Overview

Tool identifier `image_edit`.

`image_edit` performs image-to-image editing on a source image following a text instruction (replace elements, change style, and so on). The agent extracts the source image and the edit request from user input — you don't construct the parameters by hand. It uses its own edit-model environment variable, `MODEL_EDIT_NAME` (**note: different from `image_generate`'s `MODEL_IMAGE_NAME`**).

Import path: `from veadk.tools.builtin_tools.image_edit import image_edit`

## Environment & prerequisites

<Warning>
  Requirements:

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

Environment variables:

* `MODEL_EDIT_API_KEY`: API key for the image-editing 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_EDIT_NAME`: image-editing model name
* `MODEL_EDIT_API_BASE`: image-editing 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:
  edit:
    name: doubao-seededit-3-0-i2i-250628
    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. The editing model uses separate `MODEL_EDIT_*` settings.

Before running the example, set `SOURCE_IMAGE_URL` to a real image URL accessible to the editing service. The image is sent to the model service for processing.

## Usage

```python title="examples/tools/image_edit/agent.py" lines theme={null}
import asyncio
import os

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

agent = Agent(
    name="image_edit_agent",
    model_name="doubao-seed-2-1-pro-260628",
    description="Edit images on instruction.",
    instruction="You are an image-editing expert. Call image_edit with the user's source image and request.",
    tools=[image_edit],
)

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


async def main():
    response = await runner.run(
        f"In {os.environ['SOURCE_IMAGE_URL']}, replace the cat with a puppy"
    )
    print(response)


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

## Parameters and results

`image_edit(params, tool_context)` is asynchronous. It requires `params: list[dict]`, while `tool_context: ToolContext` is injected during execution. Each request supports:

| Field | Type | Default | Description |
| :- | :- | :- | :- |
| `origin_image` | `str` | Required | Source URL or `data:image/...;base64,...` |
| `prompt` | `str` | Required | Editing instruction |
| `image_name` | `str` | `generated_image_{idx}` | Result name; use distinct names in a batch |
| `response_format` | `str` | `"url"` | `url` or `b64_json` |
| `guidance_scale` | `float` | `2.5` | Prompt influence; SeedEdit 3.0 supports 1.0–10.0 |
| `watermark` | `bool` | `True` | Add a watermark |
| `seed` | `int` | `-1` | SeedEdit 3.0 supports -1 to 2147483647; -1 selects a random seed |

The result contains `status`, `success_list`, and `error_list`. Success items map names to image URLs. `status` can be `success` when some items failed, so inspect the error list as well. `b64_json` results are uploaded to TOS first and require writable object storage configuration; the default `url` skips that upload. A fixed seed does not guarantee identical images across model versions.