编辑基础图像

Agent 主路径

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

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

工具参数

{
  "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 张；auto 保留公开最多 4 张的能力。不兼容的显式请求会在计费前失败，不会丢弃图像。

当前稳定别名为 wan2.7-image-pro、wan2.7-image、qwen-image-2.0-pro 和 qwen-image-2.0。每张单价以 beatra.models.list 实时发现为准，不要把价格复制进 agent 提示词。最终按成功保存的图像数量结算，包括部分输出。

任务状态与恢复

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

REST 回退路径

自定义集成使用 POST /v1/images/edits。完整契约见生成的 API operation。REST/OpenAPI 保持为回退路径。