> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API 申請および使用方法 > OpenAI generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) ページで「Acquire」ボタンをクリックし、リクエストに必要な認証トークンを取得してください： ![](https://cdn.xhuoapi.ai/nyq0xz.png) 未ログインまたは未登録の場合は、自動的にログインページにリダイレクトされ、登録・ログイン後に元のページに戻ります。 初回申請時には無料枠が付与され、この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` で生成された科学解説の図鑑です：

これを「夜間モード」配色に変更したい場合、以下のように呼び出します： ```shell theme={null} 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で： ```python theme={null} 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) ``` 返却例： ```json theme={null} { "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` は複数の画像を参考に最終結果を生成可能です。例えば複数の製品写真を一つのギフトバスケットに合成する場合： ```python theme={null} 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` 生成の木製本棚）：

呼び出し： ```python theme={null} 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` に変更するだけです： ```python theme={null} 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` は取得したトークンを設定します： ```shell theme={null} 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:;base64,...` に変換して上流へ送信）、またはフォームフィールドに画像URL文字列を直接渡すことも可能です。 > * `mask`、`n`、`size`、`response_format` などのパラメータは非対応で、指定しても無視されます。 > * 返却構造はOpenAI形式（`data[].url`）に準拠しますが、`created` は常に `0`、`b64_json` は返さず、`revised_prompt` は常に元の `prompt` と同じです。 ### フォーム＋画像URLでの呼び出し ```shell theme={null} 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" ``` 返却例： ```json theme={null} { "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" } ] } ``` 編集後の画像：

### フォーム＋ローカルファイルでの呼び出し ```python theme={null} 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 theme={null} 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[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` 初回利用時は少なくとも4つの項目を指定する必要があります。1つは `authorization` で、ドロップダウンから選択可能です。もう1つは `model` で、OpenAI公式のモデルカテゴリを選択します。ここでは主に1種類のモデルがあり、詳細は提供モデルを参照してください。さらに `prompt` は生成したい画像の指示文です。最後に `image` は編集対象の画像パスで、以下のような画像を指定します：

同様の呼び出しをPythonで行う例： ```python theme={null} 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の場合、以下のコマンドで設定可能です： ```shell theme={null} 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 モデル](#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/](https://webhook.site/) を使います。サイトを開くとWebhook URLが取得できます： ![](https://cdn.xhuoapi.ai/cjjfly.png) このURLをコピーし、Webhookとして利用します。例：`https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab` 次に `callback_url` に上記URLを指定し、他のパラメータとともにリクエストします： ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` 呼び出し直後に以下のような結果が返ります： ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` しばらく待つとWebhook URLで編集結果を確認できます。内容例： ```json theme={null} { "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`：サーバー内部エラー ### エラー応答例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 結論 本ドキュメントを通じて、OpenAI Images Edits APIを使い、公式OpenAIの画像編集機能を簡単に利用する方法をご理解いただけました。APIの連携や利用に役立てていただければ幸いです。ご不明点があれば、いつでも技術サポートチームまでお問い合わせください。