# 参照画像で画像を変換
> 順序付き画像で新しい構図を導きます。

順序付き画像で新しい構図を導きます。

## Agent の主経路

参照画像で人物、スタイル、配置、内容を導き、構図全体は変更できる場合に `beatra.images.transform` を使用します。

1. ローカル画像を `beatra.assets.upload` でアップロードし、返された artifact ID を再利用します。
2. 1〜4 枚の画像を意味のある順序で渡します。元画像比率を選ぶと、最後の画像の比率が使われます。
3. 通常は `model: "auto"` を使用します。モデル、制御項目、キャンバス、価格を選ぶ前に、`capability: "image_to_image"` で `beatra.models.list` を呼び出します。
4. 1 つの `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 枚です。既定値は `2K / 16:9` の出力 1 枚です。
- `aspect: "source"` は最後の入力に従います。明示キャンバスでは希望の幅と高さを指定できますが、最終 artifact の実寸を確認してください。
- `output_relationship` の既定値は `independent` です。互換性があるモデルでは `sequence` を選べます。
- ネガティブプロンプト、プロンプト拡張、パレット、seed、組画像の可否は `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 枚受け取り、`1K`・`2K`・`4K` のプリセットキャンバスで `independent` 出力を必ず 1 枚生成し、prompt 上限は 20,000 文字です。明示ターゲットキャンバス、seed、ネガティブプロンプト、プロンプト拡張、推論、パレットには対応しません。公開価格は GPT Image 2 が 1K 90 / 2K 150 / 4K 230 クレジット、2.5 両モデルが 1K 180 / 2K 300 / 4K 460 クレジットです。4K `1:1` は受理されます。4K の transform `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/ja/docs/api-reference/operations/images/images_i2i_v1_images_image_to_image_post) を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。