参照画像で画像を変換

Agent の主経路

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

ローカル画像を beatra.assets.upload でアップロードし、返された artifact ID を再利用します。
1〜4 枚の画像を意味のある順序で渡します。元画像比率を選ぶと、最後の画像の比率が使われます。
通常は model: "auto" を使用します。モデル、制御項目、キャンバス、価格を選ぶ前に、capability: "image_to_image" で beatra.models.list を呼び出します。
1 つの client_request_id で一度だけ送信し、beatra.tasks.get で確認します。

AI ガイド

AI 連携 Markdown

独自アプリケーションに組み込む場合は、この 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 枚です。既定値は 2K / 16:9 の出力 1 枚です。
aspect: "source" は最後の入力に従います。明示キャンバスでは希望の幅と高さを指定できますが、最終 artifact の実寸を確認してください。
output_relationship の既定値は independent です。互換性があるモデルでは sequence を選べます。
ネガティブプロンプト、プロンプト拡張、パレット、seed、組画像の可否は 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 を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。