> ## 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_edit`。

`image_edit` 在给定原图的基础上按文本指令做图生图编辑（替换元素、改风格等）。智能体会从用户输入中提取原图与编辑要求，无需手动构造参数。它使用独立的编辑模型环境变量 `MODEL_EDIT_NAME`（**注意：与 `image_generate` 的 `MODEL_IMAGE_NAME` 不同**）。

导入路径：`from veadk.tools.builtin_tools.image_edit import image_edit`

## 环境变量与前提

<Warning>
  附加要求：

  1. 配置用于智能体推理模型的 API Key；
  2. 配置用于图像编辑的模型名称（`MODEL_EDIT_NAME`）。
</Warning>

环境变量：

* `MODEL_EDIT_API_KEY`：图像编辑模型的 API Key；未设置时依次回退到 `MODEL_AGENT_API_KEY` 和配置文件中的 `model.api_key`
* `MODEL_AGENT_API_KEY`：智能体推理模型的 API Key
* `MODEL_EDIT_NAME`：图像编辑模型名称
* `MODEL_EDIT_API_BASE`：图像编辑模型 API 地址，默认为火山方舟端点

<Note>
  凭证在工具执行时解析，而非导入时。导入工具模块不会触发客户端初始化，也不会要求凭证已配置。
</Note>

`config.yaml` 配置项：

```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
```

使用 BytePlus 时应按已开通服务显式设置对应的媒体模型名称、API 地址和 API Key；不要假定 `CLOUD_PROVIDER` 会覆盖这些媒体配置。图像或视频的能力与参数限制以所选模型服务为准。编辑模型使用独立的 `MODEL_EDIT_*` 配置

运行示例前设置 `SOURCE_IMAGE_URL` 为编辑服务可访问的真实图片 URL。原图会发送到模型服务处理

## 使用方法

```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="按指令编辑图片。",
    instruction="你是一个图片编辑专家，根据用户给定的原图与要求调用 image_edit 工具完成编辑。",
    tools=[image_edit],
)

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


async def main():
    response = await runner.run(
        f"把这张图 {os.environ['SOURCE_IMAGE_URL']} 里的猫换成一只小狗"
    )
    print(response)


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

## 参数与结果

`image_edit(params, tool_context)` 为异步函数，`params: list[dict]` 为必填请求列表，`tool_context: ToolContext` 由运行时注入。每个请求支持：

| 字段 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `origin_image` | `str` | 必填 | 原图 URL 或 `data:image/...;base64,...` |
| `prompt` | `str` | 必填 | 编辑要求 |
| `image_name` | `str` | `generated_image_{idx}` | 结果名称；批量请求应使用不同名称 |
| `response_format` | `str` | `"url"` | `url` 或 `b64_json` |
| `guidance_scale` | `float` | `2.5` | 提示词影响程度，SeedEdit 3.0 支持 1.0–10.0 |
| `watermark` | `bool` | `True` | 是否添加水印 |
| `seed` | `int` | `-1` | 随机种子，SeedEdit 3.0 支持 -1 至 2147483647；-1 表示随机 |

返回 `status`、`success_list`、`error_list`，成功项为结果名称到图像 URL 的映射。存在成功项时状态也可能为 `success`，因此还要检查失败项。`b64_json` 结果会先尝试上传到 TOS，需配置可写入的对象存储；默认 `url` 不需要此上传步骤。相同种子不应视为跨模型版本完全相同图像的保证