# ベース画像を編集
> ベース画像を保ちながら、指示または範囲指定の変更を適用します。

ベース画像を保ちながら、指示または範囲指定の変更を適用します。

## Agent の主経路

最初の画像をベースキャンバスとして保つ必要がある場合に `beatra.images.edit` を使います。後続の順序付き画像は編集の参考にできます。

1. ローカル入力を `beatra.assets.upload` でアップロードし、artifact ID を使います。
2. ベースを最初に置き、その後に最大 3 枚の参照を追加します。
3. モデル、範囲、制御項目、キャンバス、価格の互換性が重要な場合は、`capability: "image_edit"` で `beatra.models.list` を呼び出します。それ以外は `model: "auto"` を使います。
4. 1 つの `client_request_id` で一度だけ送信し、`beatra.tasks.get` で確認します。

## AI ガイド

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

## ツール引数

```json
{
  "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"
}
```

正規化された各範囲は対象画像の内側に収めます。1 入力につき最大 2 範囲です。画像全体を編集する場合は `edit_regions` を省略します。

## 上限、既定値、モデル互換性

- 順序付き入力は 1〜4 枚、出力も 1〜4 枚です。最初の画像が常にベースです。
- 編集は最初の画像比率に従う 2K キャンバスが既定です。`count` は 1 が既定です。
- 明示キャンバス、ネガティブプロンプト、プロンプト拡張、パレット、範囲、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` です。Qwen Image 3 は当初は明示指定のみで、`auto` は変わりません。リアルタイムの `pricing.options` から受理された出力解像度に一致する価格を選びます。部分出力を含め、正常に保存された画像数で精算し、参照画像の枚数ではクレジットを倍にしません。モデルや価格を agent プロンプトへ複製しないでください。

## タスクの正しい状態と復旧

終了状態になるまで同じ `task_id` を確認します。作成応答を失った場合だけ、同じ `client_request_id` と同一引数で再送します。指示、入力順、範囲、モデル、出力設定を変更した場合は新しい ID が必要です。

## REST で呼び出す

独自統合では `POST /v1/images/edits` を使用します。完全な契約は生成済みの [API operation](https://docs.beatra.ai/ja/docs/api-reference/operations/images/images_edits_v1_images_edits_post) を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。