# 编辑基础图像
> 在保留基础图像的同时执行指令或局部修改。

在保留基础图像的同时执行指令或局部修改。

## Agent 主路径

必须以第一张图像作为基础画布时，使用 `beatra.images.edit`；后续有序图像可作为参考。

1. 使用 `beatra.assets.upload` 上传本地图像并复用 artifact ID。
2. 把基础图像放在第一位，后面最多附加 3 张参考图。
3. 模型、区域、控制项、画布或价格兼容性重要时，以 `capability: "image_edit"` 调用 `beatra.models.list`；否则使用 `model: "auto"`。
4. 使用一个 `client_request_id` 只提交一次，再用 `beatra.tasks.get` 轮询。

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/images-edit.md

## 工具参数

```json
{
  "prompt": "替换选中区域内的招牌，并保留其他内容",
  "images": [
    { "type": "artifact", "artifact_id": "artifact_base" }
  ],
  "edit_regions": [
    { "image_index": 0, "x": 0.58, "y": 0.20, "width": 0.30, "height": 0.18 }
  ],
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "source" },
  "client_request_id": "img-edit-opaque-1"
}
```

每个归一化区域必须位于对应图像内部；每张输入最多 2 个区域。整图编辑应省略 `edit_regions`。

## 上限、默认值和模型兼容性

- 可传入 1–4 张有序图像并请求 1–4 张输出；第一张始终是基础图像。
- 编辑默认使用跟随第一张图比例的 2K 画布；`count` 默认为 1。
- 精确画布、负向提示词、提示词增强、调色板、区域和种子支持以 `beatra.models.list` 为准。
- 显式选择 Qwen Image 2.0 或 3.0 时最多输入 3 张；`auto` 保留公开最多 4 张的能力。不兼容的显式请求会在计费前失败，不会丢弃图像。

当前稳定别名为 `qwen-image-3.0-pro`、`qwen-image-3.0`、`wan2.7-image-pro`、`wan2.7-image`、`qwen-image-2.0-pro` 和 `qwen-image-2.0`。Qwen Image 3 首发仅支持显式选择，不改变 `auto`。从实时 `pricing.options` 选择与实际输出分辨率匹配的价格。最终按成功保存的图像数量结算，包括部分输出；输入参考图不会按张数加倍扣积分。不要把模型或价格复制进 agent 提示词。

## 任务状态与恢复

轮询同一个 `task_id` 直到终态。只有参数完全相同时，才能用同一个 `client_request_id` 恢复丢失的创建响应。指令、输入顺序、区域、模型或输出设置变化都属于新任务，需要新 ID。

## REST 回退路径

自定义集成使用 `POST /v1/images/edits`。完整契约见生成的 [API operation](https://docs.beatra.ai/zh/docs/api-reference/operations/images/images_edits_v1_images_edits_post)。REST/OpenAPI 保持为回退路径。