OpenAI Images Edits API 申請および使用方法

OpenAIの画像編集サービスは、任意の枚数の画像と指示を入力として受け取り、編集後の画像を出力します。現在、このAPIは dall-e-2、gpt-image-1、最新の gpt-image-2、および同一インターフェースで接続されている nano-banana / nano-banana-2 / nano-banana-pro シリーズのモデルをサポートしています。本ドキュメントではOpenAI Images Edits APIの操作手順を主に紹介し、これを利用して公式のOpenAI画像編集機能を簡単に使う方法を説明します。

申請手順

OpenAI Images Edits APIを使用するには、まず OpenAI Images Edits API ページで「Acquire」ボタンをクリックし、リクエストに必要な認証トークンを取得してください：

未ログインまたは未登録の場合は、自動的にログインページにリダイレクトされ、登録・ログイン後に元のページに戻ります。初回申請時には無料枠が付与され、このAPIを無料で利用可能です。

GPT-Image-2 モデル

gpt-image-2 は画像編集シーンにおいて gpt-image-1 と比べて大幅に性能が向上しています：

構造の安定維持：スキン変更、配色変更、背景変更時に元画像のレイアウトや構図がほぼ破壊されません。
文字の正確な保持：インフォグラフィック、ポスター、メニューなど文字を含む画像でも編集後に文字が鮮明に読めます。
URL直接入力対応：従来の multipart/form-data ファイルアップロードに加え、gpt-image-2 はJSON形式で画像URLを渡すことも可能で、画像をローカルにダウンロードする必要がなく、サーバーサイドのパイプライン接続に非常に適しています。
高解像度リペイント対応：1Kの元画像を入力し、size パラメータで2K/4K出力を要求可能で、編集過程で同時に拡大処理も行います。

サポートされる `size` の値と課金区分

編集APIの size の制約は生成APIと完全に同じです。gpt-image-2 は size に auto、空文字、または WIDTHxHEIGHT 形式のみを受け付け、それ以外は400エラーを返します。課金は2段階で、元画像の解像度に関係なく size のリクエスト値のみで判定されます：

1K標準価格：下表のいずれかの1K推奨サイズ、または上流の1K一般的な出力別名（1254x1254、1672x941、941x1672）。
その他区分（1.5倍）：下表の2K/4K推奨サイズおよび任意のカスタム WIDTHxHEIGHT。

上流のカスタムサイズの厳格な制約も適用されます：幅・高さは16の倍数、長辺 ≤ 3840、総ピクセル数 ≤ 8,294,400。

アスペクト比	1K（標準価格）	2K推奨（×1.5）	4K推奨（×1.5）
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

例：元画像が 1024x1024 の場合、size に 2048x2048 を指定するとモデルは編集指示に従い2K画像をリペイントし、「その他」区分で課金されます。size に 3840x2160 を指定すると4K横長画像を出力し、同様に「その他」区分で課金されます。auto または省略時は1K標準価格で課金されます。

n パラメータについて gpt-image-2 の編集APIは現時点で**n > 1 をサポートしていません**。このパラメータは無視され、n=1 でも n=10 でも単一の画像しか返されず、課金も1枚分のみです。複数の候補画像を一度に取得したい場合は、複数回のリクエストを並行して行ってください。この制約は gpt-image-1 / gpt-image-1.5 および nano-banana / nano-banana-2 / nano-banana-pro シリーズにも適用されます。dall-e-2 は現時点で唯一 n > 1 をネイティブにサポートする編集モデルです。

以下に、異なる角度からの実例を通じて gpt-image-2 の編集能力を体感してください。

呼び出し方法1：JSON + 画像URL（推奨）

application/json 形式でリクエストを送信し、image フィールドに画像のURLを指定すると、モデルがその画像を取得して prompt に従い編集します。例えば、以下の元画像は gpt-image-2 で生成された科学解説の図鑑です：

これを「夜間モード」配色に変更したい場合、以下のように呼び出します：

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

またはPythonで：

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

返却例：

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

編集後の画像：

モジュール構造、情報区分、フォント配置が厳密に保持され、配色のみがダークテーマに反転されていることがわかります。

ヒント：image フィールドは配列も受け付けます。例："image": ["url1", "url2", "url3"]。最大16枚まで同時に参考画像を渡し、モデルに複数画像を総合的に参照させて編集できます。

呼び出し方法2：JSON + 複数参考画像

gpt-image-2 は複数の画像を参考に最終結果を生成可能です。例えば複数の製品写真を一つのギフトバスケットに合成する場合：

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

シーン例：スタイル変更 + 構造維持

別の例として、木製の本棚をモダンな浮かせ棚に置き換えつつ、各段の本の数と配置は厳密に保持します。元画像（gpt-image-2 生成の木製本棚）：

呼び出し：

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

編集結果（task_id: e9544dba-727e-44a2-81e1-223d49869380）：

スタイルと環境は指示通り完全に置き換えられていますが、各段の本の数（1 / 3 / 7）は厳密に保持され、さらにトップ棚に小さな多肉植物が追加されています。

呼び出し方法3：multipart/form-data（OpenAI SDK互換）

公式OpenAI Python SDKを使っている場合、従来の multipart/form-data アップロード方式も利用可能で、model を gpt-image-2 に変更するだけです：

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

SDK利用時は環境変数を2つ設定してください。OPENAI_BASE_URL は https://api.xhuoapi.ai/v1/openai、OPENAI_API_KEY は取得したトークンを設定します：

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

Nano Banana シリーズモデル

nano-banana シリーズも編集シーンで /openai/images/edits に接続されており、model を以下のいずれかに変更するだけで利用可能です。

モデル	課金（Credits / 回）	適用シーン
`nano-banana`	0.14	一般的な画像編集、最速かつ最安価
`nano-banana-2`	0.28	品質とディテールが明確に向上
`nano-banana-pro`	0.35	シリーズのフラッグシップ、構造・文字・スタイルの保持が最良

重要：対応パラメータ範囲 Nano Bananaは適応レイヤーを通じてOpenAIプロトコルに接続されており、以下のパラメータのみサポートします：model、prompt、image。

image は multipart/form-data でファイルアップロード可能（内部で data:<mime>;base64,... に変換して上流へ送信）、またはフォームフィールドに画像URL文字列を直接渡すことも可能です。

mask、n、size、response_format などのパラメータは非対応で、指定しても無視されます。

返却構造はOpenAI形式（data[].url）に準拠しますが、created は常に 0、b64_json は返さず、revised_prompt は常に元の prompt と同じです。

フォーム＋画像URLでの呼び出し

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

返却例：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

編集後の画像：

フォーム＋ローカルファイルでの呼び出し

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

非同期コールバック

callback_url による非同期コールバック機構はnano-bananaにも有効で、他のモデルと同様の呼び出しフローです。詳細は後述の非同期コールバック節を参照してください。

基本的な使い方

以下はCURLを使った呼び出し例です：

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

初回利用時は少なくとも4つの項目を指定する必要があります。1つは authorization で、ドロップダウンから選択可能です。もう1つは model で、OpenAI公式のモデルカテゴリを選択します。ここでは主に1種類のモデルがあり、詳細は提供モデルを参照してください。さらに prompt は生成したい画像の指示文です。最後に image は編集対象の画像パスで、以下のような画像を指定します：

同様の呼び出しをPythonで行う例：

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# 画像をファイルに保存
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

Pythonで呼び出す際は、環境変数を2つ設定してください。OPENAI_BASE_URL は https://api.xhuoapi.ai/v1/openai、OPENAI_API_KEY は認証トークンです。Mac OSの場合、以下のコマンドで設定可能です：

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token} 

呼び出し後、カレントディレクトリに gift-basket.png という画像が生成されます。結果は以下の通りです：

これで画像編集操作が完了しました。現在Editsインターフェースは3種類のモデルをサポートしています：dall-e-2、gpt-image-1、gpt-image-2。その中で gpt-image-2 が推奨モデルです。詳細は上記の GPT-Image-2 モデル節を参照してください。

非同期コールバック

OpenAI Images Edits APIは画像編集に時間がかかる場合があり、APIが長時間応答しないとHTTP接続が保持され続け、システムリソースを消費します。そのため本APIは非同期コールバックもサポートしています。全体の流れは、クライアントがリクエスト時に追加で callback_url フィールドを指定し、APIは即座に task_id を含む結果を返します。編集タスク完了後、編集結果がPOSTのJSON形式でクライアント指定の callback_url に送信され、task_id でタスクを紐付けられます。以下の例で具体的な操作を説明します。まずWebhookコールバックはHTTPリクエストを受け取れるサービスで、開発者は自身で構築したHTTPサーバーのURLを指定してください。ここではデモ用に公開Webhookサイト https://webhook.site/ を使います。サイトを開くとWebhook URLが取得できます：

このURLをコピーし、Webhookとして利用します。例：https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab 次に callback_url に上記URLを指定し、他のパラメータとともにリクエストします：

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

呼び出し直後に以下のような結果が返ります：

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

しばらく待つとWebhook URLで編集結果を確認できます。内容例：

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

結果に task_id が含まれ、data フィールドには同期呼び出しと同様の編集画像結果が入っています。task_id でタスクを紐付け可能です。

エラー処理

API呼び出し時にエラーが発生した場合、APIは対応するエラーコードとメッセージを返します。例：

400 token_mismatched：不正なリクエスト、パラメータ不足や無効の可能性あり
400 api_not_implemented：不正なリクエスト、パラメータ不足や無効の可能性あり
401 invalid_token：認証エラー、無効または欠如したトークン
429 too_many_requests：リクエスト過多、レート制限超過
500 api_error：サーバー内部エラー

エラー応答例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

本ドキュメントを通じて、OpenAI Images Edits APIを使い、公式OpenAIの画像編集機能を簡単に利用する方法をご理解いただけました。APIの連携や利用に役立てていただければ幸いです。ご不明点があれば、いつでも技術サポートチームまでお問い合わせください。

​申請手順

​GPT-Image-2 モデル

​サポートされる size の値と課金区分

​呼び出し方法1：JSON + 画像URL（推奨）

​呼び出し方法2：JSON + 複数参考画像

​シーン例：スタイル変更 + 構造維持

​呼び出し方法3：multipart/form-data（OpenAI SDK互換）

​Nano Banana シリーズモデル

​フォーム＋画像URLでの呼び出し

​フォーム＋ローカルファイルでの呼び出し

​非同期コールバック

​基本的な使い方

​非同期コールバック

​エラー処理

​エラー応答例

​結論

申請手順

GPT-Image-2 モデル

サポートされる `size` の値と課金区分

呼び出し方法1：JSON + 画像URL（推奨）

呼び出し方法2：JSON + 複数参考画像

シーン例：スタイル変更 + 構造維持

呼び出し方法3：multipart/form-data（OpenAI SDK互換）

Nano Banana シリーズモデル

フォーム＋画像URLでの呼び出し

フォーム＋ローカルファイルでの呼び出し

非同期コールバック

基本的な使い方

非同期コールバック

エラー処理

エラー応答例

結論