tutorial9 分で読める

GPT Image 2 の画像編集 API でインペインティングとアウトペインティングを使いこなす

現行の GPT Image 2 契約で既存画像を編集する。gpt-image-2 では参考画像によるプロンプト誘導、gpt-image-2-official ではマスクによる精密なインペインティング。いずれも非同期の generations エンドポイントを使う。

ToAPIs Engineering & Evaluation Team
TL;DR - 要点まとめ
  • 現行の ToAPIs 画像契約は非同期の POST /v1/images/generations であり、同期 multipart の /v1/images/edits でも、カタログ ID gpt-image-2-edit でもない。
  • 正確な gpt-image-2 は reference_images(公開 URL のみ、最大 14 枚)によるプロンプト誘導編集に対応する。アルファマスクによるピクセル精度のインペインティングは、gpt-image-2-official の mask_url と image_urls として文書化されている。
  • size は 1:1 や 16:9 などのアスペクト比、resolution は 1k / 2k / 4k のティアである。size に 1024x1024 のようなピクセル文字列を送ってはならない。
  • 文書化された outpaint フラグはない。キャンバスを広げるには、size を目的の比率に変え、原図を参考画像として渡し、プロンプトで拡張内容を指示する。
  • タスク id を永続化し、GET /v1/images/generations/{id} をポーリングする。クライアントのタイムアウトは、タスク失敗の証明にはならない。

GPT Image 2 の画像編集 API でインペインティングとアウトペインティングを使いこなす

対象モデル: gpt-image-2、gpt-image-2-official
推論エンドポイント: https://api.toapis.com/v1/images/generations
関連: GPT Image 2 API ガイド · 4K アスペクト比ワークフロー · グローバルミラーとプロキシ · 公式インペインティングリファレンス


1. クイックスタートと性能概要 (TL;DR)

  • 目的: 既存画像の一部を置き換える(インペインティング)、または新しいアスペクト比へキャンバスを広げる(アウトペインティング)。文書化されていない第二の API を作らない。
  • 契約: カタログに実在するモデル ID を使う。正確な gpt-image-2 は prompt、比率としての size、1k / 2k / 4k の resolution、任意の reference_images を受け付ける。マスク付きインペインティングは gpt-image-2-official で、image_urls と mask_url として文書化されている。
  • 現行契約ではないもの: gpt-image-2-edit というモデル ID、同期 multipart の POST /v1/images/edits、size: "1024x1024"。古い原稿に現れる形であり、新しいクライアントへコピーしてはならない。
  • 入出力: ソース画像とマスクは POST /v1/uploads/images でアップロードし、返却された公開 URL を渡す。reference_images、image_urls、mask_url は base64 を受け付けない。
  • 非同期プロトコル: 投入はタスク id を返す。GET /v1/images/generations/{id} を completed または failed までポーリングする。クライアントのタイムアウトは失敗の証明ではない。

2. プログラムによる画像編集の実務的な価値

テキストから静止画を生成するのは最初の一歩にすぎない。本番のカタログ、広告、デザインシステムでは、より多く狙った修正が必要になる。商品の差し替え、背景の整理、正方形のパッケージ写真を横長ヒーローへ伸ばす、といった作業を、照明と被写体の同一性を保ちながら行う。

現行の ToAPIs GPT Image 2 ファミリーは、これらの仕事を一本のパス POST /v1/images/generations で扱い、違いはモデル ID にある。

作業モデル IDソースの指定方法マスク
プロンプト誘導の編集やスタイル変換gpt-image-2reference_images(URL リスト、最大 14)この ID では文書化されていない
ピクセル精度のインペインティングgpt-image-2-officialimage_urls(URL リスト、最大 16)先頭画像とともに mask_url が必要
キャンバス拡張(アウトペインティング)いずれの ID でも可原図を参考画像として渡し、size を目的の比率へ変更専用の outpaint フラグはない

正確な gpt-image-2 では、image_urls は reference_images の後方互換エイリアスで、ゲートウェイが正規化する。公式チャネルの API リファレンス例は image_urls と mask_url を併用する。実際に呼ぶ ID のリファレンスにあるフィールド名を使うこと。

使えるインペインティングマスクはアルファチャネル付き PNG で、ピクセル寸法は先頭の参考画像と一致しなければならない。透明ピクセル(alpha = 0)が再生成領域、不透明ピクセルは保持されるべきである。パイプライン(Pillow など)でマスクを作り、アップロードして URL だけを送る。

アウトペインティングはワークフローであり、別エンドポイントではない。1:1 のパッケージ写真を 16:9 のバナーにしたい場合は、原図を参考画像として残し、size を 16:9 にし、resolution ティアを明示し、被写体を保って場面を広げるよう指示する。実用的な変形として、原図をより大きな透明キャンバスへ合成してアップロードし、それを参考画像とする方法もある。それでもパスは /v1/images/generations であり、outpaint: true のようなフラグはない。

マスクの島状フレームが六角形ゲートウェイを通って拡張キャンバスへ流れる

図 1: ソースキャンバスと内側のマスク領域が ToAPIs ゲートウェイを通過する。文書化されたパスは依然として POST /v1/images/generations であり、mask_url は gpt-image-2-official 向けに予約されている。

size と resolution はテキスト生成と同じ契約に従う。size は 1:1 や 16:9 のような比率、resolution は 1k、2k、4k。正確な gpt-image-2 は現行プレイグラウンド契約で quality を公開しない。quality(low / medium / high)は gpt-image-2-official に現れる。ピクセル表は 4K ワークフローガイド を参照。


3. 本番実装: cURL と Python

本シリーズの国際向け例は https://api.toapis.com を使う。公式ドキュメントは中国本土の利用者に https://toapis.cn を使うよう案内している。環境ごとにオリジンは一つに保つ。パス、モデル ID、Bearer ヘッダーは同じままである。

ステップ 1: ソース画像をアップロードする(マスクが必要なら同様に)

bash
curl -X POST "https://api.toapis.com/v1/uploads/images" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -F "file=@./product.png"

応答に data.url が含まれる。gpt-image-2-official を呼ぶ場合は、マスク PNG でも同じ呼び出しを繰り返す。生成リクエストに base64 を埋め込まないこと。

ステップ 2: 正確な gpt-image-2 でのプロンプト誘導編集

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url",
    "reference_images": ["https://example.com/product.png"]
  }'

ステップ 3: gpt-image-2-official でのマスク付きインペインティング

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-official",
    "prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'

ステップ 4: Python の投入とポーリング

フィールド名は、呼び出すモデル ID の API リファレンスに合わせる。次の断片は文書化された画像ステータスパスと、completed / failed ステータスを使う。

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def upload_image(path: str) -> str:
    with open(path, "rb") as handle:
        res = requests.post(
            f"{BASE}/v1/uploads/images",
            headers=HEADERS,
            files={"file": handle},
            timeout=60,
        )
    res.raise_for_status()
    url = res.json().get("data", {}).get("url")
    if not url:
        raise RuntimeError(f"Unexpected upload envelope: {res.text}")
    return url


def dispatch_edit(payload: dict) -> str:
    res = requests.post(
        f"{BASE}/v1/images/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json=payload,
        timeout=30,
    )
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(
        f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
    )


if __name__ == "__main__":
    source = upload_image("product.png")
    # Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
    task_id = dispatch_edit(
        {
            "model": "gpt-image-2",
            "prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
            "size": "16:9",
            "resolution": "1k",
            "n": 1,
            "response_format": "url",
            "reference_images": [source],
        }
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

マスク付きインペインティングに切り替える場合は、先頭画像と同じ寸法の RGBA マスクをアップロードし、model を gpt-image-2-official にし、image_urls と mask_url を送る。モデル ID、size、resolution はタスク記録と一緒に保存し、後の SKU 変更を明示的な判断にする。


4. エラー処理とステータスマトリクス

次の分類は切り分けの出発点であり、ToAPIs の正確なエラーコードを保証するものではない。HTTP 投入が成功しても、タスクの status を読む必要がある。

HTTP ステータスよくある分類推奨アクション
400不正なフィールド、または未対応の組み合わせモデル ID、size が文書化された比率であること、resolution が 1k / 2k / 4k であること、URL が公開されていること、マスクを使う場合は gpt-image-2-official 上で先頭画像と同寸法のアルファ付き PNG であることを確認する
401API キーの欠落または無効ToAPIs ダッシュボードでキーをローテーションし、Authorization ヘッダーを確認する
429レートまたは同時実行の制限Retry-After があれば従い、ジッター付きでバックオフし、安全なときだけ再試行する
5xx またはネットワークタイムアウトゲートウェイまたは上流の一時的な問題再投入の前にタスク状態を確認し、上限付きの再試行方針を使う

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. 料金と FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • 企画段階の古い単価を再利用しないこと。たとえば固定の $0.024 / $0.048(standard 対 HD)といった組み合わせは、現行カタログから見て古い。現行カタログはモデル ID で決まり、標準 GPT Image 2 のランディング比較では解像度ティアでも分かれる。
  • GPT Image 2 モデルガイド は現在、標準 gpt-image-2 について ToAPIs ランディング比較として 1K / 2K / 4K で 1 枚あたり $0.015 / $0.020 / $0.025 を示している。これは掲載上の比較であり、請求書そのものではない。公式チャネルの SKU やアカウント割引は異なり得る。実際に呼ぶ ID のレートを確認すること。
  • ルーティング(api.toapis.com と toapis.cn)はベース URL の選択であり、文書化された割引ではない。FinOps 上の効果は、1k で下書きすること、クライアントタイムアウト後の重複投入を避けること、正しい SKU(gpt-image-2 と gpt-image-2-official)を選ぶことから来る。「編集用の安いモデル」を想像してはならない。
  • 背景は GPT Image 2 料金記事 を参照し、予測に入れる前に現行カタログで数字を検証すること。

6. よくある質問

詳細は frontmatter の FAQ を参照。要約: 正確な gpt-image-2 には mask_url も /v1/images/edits も文書化されていない。マスク付きインペインティングは gpt-image-2-official に文書化されている。マスクは同寸法の RGBA PNG を URL で渡す。アウトペインティングは size の変更と参考画像である。課金は正確なモデル ID についてアカウントで確認する。


7. アクションチェックリスト

  • ToAPIs 開発者ポータル でキーを作成する。
  • 環境ごとにベース URL を一つに決め(https://api.toapis.com、必要な場合は https://toapis.cn)、POST /v1/uploads/images でソース画像をアップロードする。
  • gpt-image-2 でプロンプト誘導編集をスモークテストする。reference_images、size: "1:1"、resolution: "1k" を使う。
  • ピクセル精度のマスクが必要なら gpt-image-2-official に切り替え、先頭画像と一致する RGBA マスクをアップロードし、image_urls と mask_url を送る。
  • タスク id を永続化し、期限付きで GET /v1/images/generations/{id} をポーリングし、429 では Retry-After に従う。
  • 次の読み物: resolution を上げるなら 4K アスペクト比ガイド、パラメータ全体は API ガイド。

記事内で紹介されたモデルとAPI

OpenAIIMAGE

GPT-Image-2

現在のレート:3 credits /request
OpenAIIMAGE

gpt-image-2-official

現在のレート:Input 800 credits/1M, Output 4,800 credits/1M

関連記事