GPT Image 2 / 2.5 API — Generation and Image Editing

Use generations for text-to-image and multipart edits for reference images with GPT Image 2, Sunburst and Flare. Includes single-image, multi-image, Python and async examples.

GPT Image 2 / 2.5: 画像生成と画像編集

リクエストを書く前にエンドポイントを選択してください: テキストから画像への生成には /images/generations を、画像から画像への編集にはアップロードした画像ファイルとともに /images/edits を使用します。プロンプト内で「参照画像1」と言及しても、画像は添付されません。

モデルとエンドポイント

モデル ID	テキストから画像	画像から画像
`gpt-image-2`	`/images/generations`	`/images/edits` + 画像ファイル
`gpt-image-2.5-sunburst`	`/images/generations`	`/images/edits` + 画像ファイル
`gpt-image-2.5-flare`	`/images/generations`	`/images/edits` + 画像ファイル

これらは異なるモデル ID です。モデルを切り替える際は model を明示的に変更してください。GPT Image 2.5 は GPT Image 2 のエイリアスではありません。現在の利用可能状況やアカウントの価格についてはマーケットプレイスをご確認ください。

操作	メソッドとエンドポイント	リクエスト形式
テキストから画像	`POST https://apimaster.ai/v1/images/generations`	JSON
画像から画像 / 編集	`POST https://apimaster.ai/v1/images/edits`	実際の画像ファイルによる `multipart/form-data`
非同期画像編集	`POST https://apimaster.ai/v1/images/edits/async`	編集と同じマルチパートファイル。タスク ID を返します
非同期テキストから画像	`POST https://apimaster.ai/v1/images/generations/async`	JSON。タスク ID を返します
タスクの照会	`GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID`	Bearer 認証

画像編集のタスク応答を取得するには、/images/edits/async を使用してください。 同期編集と同じファイルとフィールドをアップロードし、その後 /tasks/{task_id} を照会します。編集リクエストを generations/async に移動しないでください。これらのタスクエンドポイントは既存の非同期契約を再利用します。非同期のアップストリームはタスクを即座に返すことができますが、同期のアップストリームはゲートウェイがタスク ID を返す前に編集を完了する場合があります。これらは即時のバックグラウンド実行を保証するものではありません。これらのモデルに Chat Completions を使用しないでください。

認証とタイムアウト

API キーを作成し、Authorization: Bearer YOUR_API_KEY を送信してください。JSON 生成リクエストでは Content-Type: application/json を使用します。ファイルのアップロードでは、マルチパートの境界(boundary)は cURL または使用中の HTTP ライブラリに生成させてください。Content-Type ヘッダーを手動で設定しないでください。

基本的なリクエストには少なくとも 180 秒、高解像度には 300 秒、負荷の高い編集や高品質には 600 秒を確保してください。クライアントのタイムアウトは、アップストリームのリクエストが停止したことを証明するものではありません。即時の重複送信は避けてください。

テキストから画像: JSON 生成

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Sunburst または Flare の場合は、モデル ID を gpt-image-2.5-sunburst または gpt-image-2.5-flare に置き換えてください。この例に参照画像を追加しないでください。参照画像には以下の編集例を使用します。

画像から画像: 参照画像を 1 枚アップロード

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

reference.png を実在するローカル画像に置き換えてください。@ は cURL にファイルのバイト列をアップロードさせます。image=reference.png はファイル名の文字列のみを送信します。このエンドポイントのパターンは gpt-image-2 と gpt-image-2.5-sunburst にも同様に適用されます。

画像から画像: 複数の参照画像をアップロード

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

各ファイルについて、プロンプトで記述した順序どおりに同じ image[] フィールドを繰り返してください。n は参照画像の数ではなく、出力画像の枚数です。参照画像の上限は選択したモデルと利用可能なルートに依存します。一律に 16 枚の上限があると想定しないでください。まず 1 枚の参照画像と n=1 から始め、必要に応じて入力を追加してください。

Python 編集例

requests をインストールしてください。この例では実際のファイルをアップロードし、URL と base64 の両方の画像応答を処理します。

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

複数のファイルの場合は、繰り返しの ("image[]", (filename, file_object, mime_type)) エントリのリストを files に渡します。リクエストが完了するまで各ファイルを開いたままにしてください。

非同期画像編集

アプリケーションがタスク ID を扱う場合に、GPT Image 2、Sunburst、Flare に対してこのエンドポイントを使用してください。ファイルのアップロード規則、参照画像の順序、機能の上限、認証は同期編集と同じです。

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

送信は data[0].task_id を返します。同じモデル ID を使用してポーリングします:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

完了した追跡対象タスクは次の形式を持ち、生成されたすべての画像が含まれます:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

タスクは送信したアカウントに帰属します。そのアカウントの有効な API キーで照会してください。失敗した送信は利用可能なタスクではなくエラーを返します。タスク ID が返された後は、編集を再送信するのではなく、そのタスクのポーリングを継続してください。以下のポーリングステータス表を参照してください。

既存の URL または base64 連携の取り込み

入力が URL の場合は、アプリケーション内で画像をダウンロードし、そのバイト列を /images/edits にアップロードしてください。base64 データ URI の場合は、ペイロードをファイルまたはバイトバッファにデコードしてアップロードしてください。URL や base64 テキストをファイルのアップロードであるかのように送信しないでください。

一部の GPT Image 2 ルートは、generations 上の拡張 image_urls に対応しています。これは移植可能な画像編集の契約ではなく、GPT Image 2.5 で動作すると想定してはなりません。 新規の連携では、上記のマルチパート編集の例を使用してください。image_urls、image または images を含む JSON リクエストは、edits へのファイルのアップロードと同等ではありません。

パラメータと機能の上限

フィールド	使い方
`model`	必須。上記の表から正確なモデル ID を 1 つ使用
`prompt`	必須。結果と参照画像の順序を記述
`image` / `image[]`	編集用に実際にアップロードしたファイル。基本の例では PNG または JPEG を使用
`n`	出力画像の枚数。`1` から開始。最大値はルートに依存
`size`	任意。`1024x1024` が基本の例。その他のピクセル寸法やアスペクト比はルートに依存
`resolution`	任意のルート固有の拡張。`1k`、`2k`、`4k` など。すべてのモデル/ルートですべてのティアに対応しているわけではない
`quality`	任意。受け付けられる値とコストはルートに依存
`background`、`output_format`、`output_compression`	任意。透過および出力エンコーディングにはルートの対応が必要
`mask`	GPT Image 2 のみ。利用可能な edits ルートがアップロードされたマスクに対応している場合。現在の GPT Image 2.5 マルチパートハンドラでは非対応

GPT Image 2 の場合、マスクの対応は通常の参照編集とは別に確認する必要があります。互換性のある PNG マスクは入力画像と寸法が一致し、アルファチャンネルを含む必要があります。現在の GPT Image 2.5 マルチパートエンドポイントはアップロードされたマスクファイルを拒否します。上記の Sunburst または Flare の例にマスクを追加しないでください。選択したルートを確認せずに、JSON の mask_url による回避策が対応していると想定しないでください。

必要な任意フィールドのみを送信してください。これらは適用可能なルートと価格を変える可能性があります。デフォルト値を明示的に設定することは、省略することと必ずしも同等ではありません。一律に 3 つのすべてのモデル ID に適用される固定のピクセルサイズ表や高度なパラメータのリストは存在しません。実際の価格と対応機能はマーケットプレイスとリクエストの応答に従います。

同期応答

生成または編集が成功すると、data に画像エントリが返されます:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

ルートと出力形式によっては、エントリの代わりに b64_json が含まれる場合があります。それを画像バイトにデコードしてください。一時的な結果 URL は速やかにダウンロードしてください。HTTP 200 の応答や画像の枚数だけでは、参照画像のディテールが保持されたことを証明するものではありません。入力と結果を目視で比較してください。

非同期タスク: 送信とポーリング

テキストから画像の場合は、参照画像なしの JSON を generations/async に送信します。画像編集の場合は、上記のマルチパートの edits/async の例を使用します。どちらも同じタスク照会エンドポイントを使用します:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

送信のエンベロープは通常 submitted を報告します。アップストリームがすでに完了状態を報告している場合もあります。最初のポーリングで完了していることもあります。タスク ID は即時の応答を保証しません。選択したアップストリームが同期型の場合、プラットフォームはタスクを返す前に生成の完了を待機します。十分な送信タイムアウトを確保してください。

送信時に使用したのと同じモデル ID でポーリングします:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

タスクステータス	対処
`pending`、`submitted`、`processing`、`in_progress`	待機。3〜5 秒後に再照会
`succeeded`、`success`、`completed`	`data.result.images` のすべてのエントリを読み取る。追跡対象タスクは文字列の `url` を使用しますが、レガシーなアップストリーム応答では URL 配列が使用される場合があります
`failed`、`error`、`cancelled`	ポーリングを停止し、エラーを確認

10 分など、有限の全体ポーリング期限を設けてください。期限が切れた場合は、自動的に別の有料タスクを作成するのではなく、後で確認できるようタスク ID を保持してください。タスク照会の応答と同期画像応答では構造が異なります。

参照画像のトラブルシューティング

実際のリクエストパスが /v1/images/edits または /v1/images/edits/async であり、generations や generations/async でないことを確認してください。
マルチパートに、生成された境界(boundary)とともに image または繰り返しの image[] の下にファイルのバイト列が含まれていることを確認してください。プロンプトのテキスト、ファイル名、参照数はファイルの代わりにはなりません。
正確なモデル ID を確認してください。GPT Image 2 の拡張が Sunburst や Flare で自動的に対応されるとは限りません。
タスク/ログの詳細にプレビューが表示されない場合でも、画像が送信されなかったと結論しないでください。ログには base64 データやアップロードされたファイルの内容が含まれないことがあります。逆に、ログに記録された参照数は、アップストリームがその画像を使用したことを証明するものではありません。
特徴的な文字や図形を含む簡単な参照画像でテストし、それらのディテールを記述せずに背景の変更を依頼してください。出力を目視で比較してください。
サポートに問い合わせる際は、リクエスト ID(X-Oneapi-Request-Id)、存在する場合はタスク ID、モデル、エンドポイント、タイムスタンプ、サニタイズしたリクエストフィールド、参照画像を保持してください。API キーは決して共有しないでください。

400 の応答の場合は、エンドポイントとパラメータの互換性を確認してください。401 は認証の失敗、429 はレート/クォータ制限を示します。タイムアウトやアップストリームの障害の場合は、リクエスト/タスク ID を保持し、再送信する前に既存のタスクや利用記録を確認してください。