使用参考图变换图像

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.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、gpt-image-2.5-flare、gpt-image-2.5-sunburst 和 gpt-image-2。图生图 auto 已包含 Qwen Image 3。GPT Image 2.5 Flare 与 Sunburst 在图生图 auto 中排在 Qwen / Wan 之后、gpt-image-2 之前；支持最多 4 张有序参考图和恰好 1 张 independent 输出，只接受 1K、2K 或 4K 预设画布，prompt 上限 20000 字符；不支持目标画布、seed、负向提示词、提示词增强、推理或调色板。公开价格：GPT Image 2 为 1K 90 / 2K 150 / 4K 230 credits，两个 2.5 模型为 1K 180 / 2K 300 / 4K 460 credits。4K 1:1 可以准入。4K 图生图 auto 会选 Flare。

从 beatra.models.list 的 pricing.options 选择与准入输出分辨率匹配的价格。任务只按成功保存的图像收费；参考图数量不会乘入客户 credits，隐藏的供应商输入成本由 Beatra 覆盖。不要把模型或价格复制进 agent 提示词。

任务状态与恢复

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

REST 回退路径

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