# 使用参考图变换图像
> 让有序图像引导新的构图。

让有序图像引导新的构图。

## Agent 主路径

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

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

## AI 指南

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

## 工具参数

```json
{
  "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 积分，两个 2.5 模型为 1K 180 / 2K 300 / 4K 460 积分。4K `1:1` 可以接受。4K 图生图 `auto` 会选 Flare。

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

## 任务状态与恢复

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

## REST 回退路径

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