参照画像で画像を変換

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.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 credits、2.5 両モデルが 1K 180 / 2K 300 / 4K 460 credits です。4K 1:1 は受理されます。4K の transform 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 を参照してください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。