使用参考图变换图像

Agent 主路径

参考图用于引导身份、风格、布局或内容，且允许整体构图变化时，使用 beatra.images.transform。

使用 beatra.assets.upload 上传本地图像，并复用返回的 artifact ID。
按语义顺序传入 1–4 张图像。使用来源比例时，画布跟随最后一张图。
普通请求使用 model: "auto"。需要选择模型、控制项、画布或价格时，以 capability: "image_to_image" 调用 beatra.models.list。
用一个 client_request_id 只提交一次，再用 beatra.tasks.get 轮询。

AI 指南

给 AI 的集成说明

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

工具参数

{
  "prompt": "保持角色可识别，把场景改为冬季集市",
  "images": [
    { "type": "artifact", "artifact_id": "artifact_character" },
    { "type": "artifact", "artifact_id": "artifact_style" }
  ],
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" },
  "output_relationship": "independent",
  "client_request_id": "img-transform-opaque-1"
}

实时模型信息会说明可用的 HTTPS URL、artifact ID 和小型 data URI 输入。上传过的本地文件或重复使用的图像优先用 artifact ID。

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

可传入 1–4 张有序图像，并请求 1–4 张输出；默认输出 1 张 2K / 16:9 图像。
aspect: "source" 跟随最后一张输入。目标画布可以请求明确宽高，最终仍以 artifact 实际尺寸为准。
output_relationship 默认为 independent；兼容模型可使用 sequence。
负向提示词、提示词增强、调色板、种子和组图支持以 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。

单价与 successful_image_count 结算依据以 beatra.models.list 实时发现为准，不要把价格复制进 agent 提示词；任务只按成功保存的图像收费。

任务状态与恢复

任务处于 queued 或 running 时继续轮询同一个 task_id。若创建响应丢失，使用同一个 client_request_id 和完全相同的参数恢复。参考图、顺序、提示词、模型或控制项发生变化时，必须使用新 ID。

REST 回退路径

自定义集成使用 POST /v1/images/image-to-image。完整结构见生成的 API operation。REST/OpenAPI 保持为回退路径。