OpenAI Images Edits API 申請及使用

OpenAI generation API guide - Ace Data Cloud

OpenAI 画像編集サービスでは、任意の数の画像と指示を入力し、修正後の画像を出力できます。現在、インターフェースは gpt-image-1、最新の gpt-image-2、および同じインターフェースを介して接続される nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro シリーズモデルを同時にサポートしています。

この文書では、OpenAI Images Edits API 操作の使用フローを主に紹介します。これを利用することで、公式の OpenAI 画像編集機能を簡単に使用できます。

​

申請フロー

OpenAI Images Edits API を使用するには、まず Ace Data Cloud コントロールセンター にアクセスして、API トークンを取得し、保管しておきます。

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、コントロールセンター で一般的な残高をチャージできます。

📘 完全な文書：OpenAI Images Edits API →

​

GPT-Image-2 モデル

gpt-image-2 は、画像編集シーンにおいて gpt-image-1 に比べて非常に明確な改善があります：

• 構造がより安定：スキン変更、配色変更、背景変更時に、元の画像のレイアウトや構図がほとんど破壊されません。
• 文字の保持がより正確：情報図、ポスター、メニューなどの文字を含む画像は、編集後も文字が明瞭に読めます。
• URL 直送をサポート：従来の multipart/form-data ファイルアップロードに加えて、gpt-image-2 はJSON 形式で画像 URL を直接渡すことを追加でサポートしており、画像をローカルにダウンロードする必要がなく、サーバー側のパイプライン接続に非常に適しています。
• base64 直送をサポート：公式と同様に、image フィールドには直接 base64（data:image/png;base64,... または生の base64）を渡すこともでき、ローカル画像を先にアップロードすることなく編集できます。
• 高解像度の再描画をサポート：1K の元画像を渡し、size パラメータで 2K / 4K 出力をリクエストできます。モデルは編集プロセス中に同時に拡大を完了します。

​

回線バリアント（:official / :reverse）

gpt-image-2 はデフォルトで標準回線を使用します。モデル名のサフィックスを通じて回線を明示的に選択できます：

• gpt-image-2:official：公式チャネルで、安定しており、準拠しています。実際の 2K / 4K 高解像度をサポートし、画像ごとに課金され、単価はデフォルトの gpt-image-2 の 2 倍です。回線が利用できない場合は直接エラーを返し、自動的にダウングレードされません。
• gpt-image-2:reverse：デフォルトの gpt-image-2 と完全に同等で、コストパフォーマンスが高く、価格は変わりません。

​

サポートされている size の値

編集インターフェースの size に対する制約は生成インターフェースと完全に一致します——gpt-image-2 は size が auto、空、または WIDTHxHEIGHT 形式に合致する限り、他の形態は 400 を返します。すべてのサイズ（1K / 2K / 4K / カスタム）は、単一の画像ごとに統一して課金され、元画像の解像度や size リクエスト値には関係ありません。

サイズ制限：カスタムサイズは幅と高さが両方とも 16 の倍数であり、長辺 ≤ 3840、総ピクセル数 ≤ 8,294,400 を満たす必要があり、超過すると 4xx が返されます。

比率	1K 推奨	2K 推奨	4K 推奨
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 を渡すか省略すると、モデルが自動的に選択します。三者の課金は同じです。

n パラメータについて gpt-image-2 編集インターフェースは n > 1 をサポートしています：1回のリクエストで、対応する数の編集結果を返し、画像ごとに課金されます（n の値は 1–10）。同様に gpt-image-1 / gpt-image-1.5、および nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro シリーズにも適用されます。注意：response_format=b64_json は n=1 のみサポートされ、n>1 の場合はデフォルトの URL 返却を使用してください。生成に失敗した画像があっても、成功した部分のみが返され、課金されます。

以下に、2つの異なる方向からの実際の例を通じて gpt-image-2 の編集能力を体感します。

​

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

直接 application/json 方式でリクエストを送信し、image フィールドに画像の URL を入力します。モデルはその画像を取得し、prompt に従って編集します。

例えば、以下の画像は gpt-image-2 で生成された科学普及図鑑です：

これを「夜間モード」配色に変更したいと考えています。次のように呼び出すことができます：

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/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.acedata.cloud/openai/images/edits"

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

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "このインフォグラフィックをダークモードに変換してください：ダークネイビーバックグラウンド、ライトクリームテキスト、深いグレーの丸みを帯びたモジュールカードに柔らかい影。すべてのレイアウト、構造、モジュールの配置を同じに保ち、色のスキームだけを反転させてください。",
    "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": "このインフォグラフィックをダークモードに変換してください：ダークネイビーバックグラウンド、ライトクリームテキスト、深いグレーの丸みを帯びたモジュールカードに柔らかい影。すべてのレイアウト、構造、モジュールの配置を同じに保ち、色のスキームだけを反転させてください。",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

編集後の画像は以下の通りです：

モジュールの構造、情報の区分、フォントのレイアウトが厳密に保持されており、配色だけがダークテーマに反転されています。

ヒント：image フィールドは配列を受け入れることもでき、例えば "image": ["url1", "url2", "url3"] のように最大16枚の参照画像を同時に渡し、モデルが複数の画像を総合的に参照して編集を行うことができます。

base64 直接送信：image（および配列内の各項目）はURLの他にbase64も可能です —— data:image/png;base64,... または生のbase64でも構いません。これは、ローカル画像を先にアップロードしたくないシーンに適しています。例えば：

import base64, requests
b64 = base64.b64encode(open("input.png", "rb").read()).decode()
payload = {
    "model": "gpt-image-2",
    "image": f"data:image/png;base64,{b64}",
    "prompt": "このインフォグラフィックをダークモードに変換してください。",
    "size": "1024x1536"
}
requests.post("https://api.acedata.cloud/openai/images/edits", json=payload,
              headers={"authorization": "Bearer {token}"})

​

呼び出し方法二：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": "上記のすべてのアイテムをクリーンな白い背景の上にある単一の「リラックス＆リワインド」ギフトバスケットにまとめてください。フォトリアリスティックで、柔らかい自然光を使用してください。",
    "size": "1024x1024"
}

​

シーンの例：スタイルを変更 + 構造を保持

以下は別の例で、木製の本棚を現代的な浮き棚に置き換えますが、各段の本の数と配置は厳密に保持します。

元の画像（gpt-image-2 で生成された木製の本棚）：

呼び出し：

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "木製の本棚をパステルブルーの壁に取り付けられたスリークな現代的な白い浮き棚に置き換えてください。正確に同じ本の配置を保ってください（上に1冊、中に3冊、下に7冊）。上の棚に本の隣に小さな多肉植物を追加してください。左からの明るい空気のような日光。",
    "size": "1024x1024"
}

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

スタイルと環境は指示に従って完全に置き換えられましたが、各段の本の数（1 / 3 / 7）は依然として厳密に保持され、要求に応じて多肉植物が追加されました。

​

呼び出し方法三：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="この画像をダークモードに変換し、レイアウトをそのまま保持してください。"
)

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.acedata.cloud/openai に設定し、OPENAI_API_KEY を取得したトークンに設定します：

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

​

Nano Banana シリーズモデル

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

モデル	料金（クレジット / 回）	適用シーン
nano-banana	0.14	一般的な画像編集、最速でコストが最も低い
nano-banana-2-lite	0.14	Gemini 3.1 軽量画像モデル、1Kのみサポート、低遅延編集
nano-banana-2	0.28	品質と詳細が明らかに向上
nano-banana-pro	0.35	シリーズのフラッグシップ、構造、テキスト、スタイル保持が最良

重要：パラメータサポート範囲 Nano Bananaはアダプタ層を介してOpenAIプロトコルに接続し、以下のパラメータのみをサポートします：model、prompt、image、n。

• imageはmultipart/form-dataを介してファイルをアップロードすることもできます（ローカルファイルは自動的にbase64に変換されます）、またはフォームフィールドを介して画像URL文字列を直接渡すこともできます。
• mask、size、response_formatなどのパラメータはサポートされていません；入力しても無視されます。n > 1はサポートされており（1–10）、対応する数の編集結果が返され、料金が請求されます。
• 返される構造はOpenAIフォーマット（data[].url）に従いますが、createdは固定で0となり、b64_jsonは返されず、revised_promptは常に元のpromptと等しくなります。

​

フォーム + 画像URLを使用した呼び出し

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=リンゴの上に緑の葉を追加する" \
  -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

返される結果は以下の通りです：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "リンゴの上に緑の葉を追加する"
    }
  ]
}

編集された画像：

​

フォーム + ローカルファイルを使用した呼び出し

import requests

url = "https://api.acedata.cloud/openai/images/edits"

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

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "リンゴの上に緑の葉を追加する"
}

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.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=これらのアイテムを含む素敵なギフトバスケットを作成する'

このインターフェースを初めて使用する際には、少なくとも4つの内容を入力する必要があります。1つはauthorizationで、ドロップダウンリストから直接選択できます。もう1つのパラメータはmodelで、modelはOpenAI公式サイトのモデルカテゴリを選択することを意味します。ここでは主に1種類のモデルがあります。詳細は提供されたモデルを参照してください。もう1つのパラメータはpromptで、promptは生成する画像のためのヒントです。最後のパラメータはimageで、このパラメータは編集する画像のパスを指定する必要があります。編集する画像は以下のようになります：

同じ呼び出し効果のPythonサンプル呼び出しコード：

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
白い背景に「リラックス＆リラックス」とラベル付けされたギフトバスケットのフォトリアリスティックな画像を生成し、リボンと手書き風のフォントで、参照画像に含まれるすべてのアイテムを含めます。
"""

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つの環境変数をインポートする必要があります。1つはOPENAI_BASE_URLで、https://api.acedata.cloud/openaiに設定できます。もう1つは使用する認証変数OPENAI_API_KEYで、この値はauthorizationから取得されます。Mac OSでは、以下のコマンドを使用して環境変数を設定できます：

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

呼び出し後、現在のディレクトリにgift-basket.pngという画像が生成されることがわかります。具体的な結果は以下の通りです：

これで画像の編集操作が完了しました。現在、Editsインターフェースはgpt-image-1とgpt-image-2の2種類のモデルをサポートしており、gpt-image-2は現在推奨されるモデルです。詳細は上記のGPT-Image-2モデルセクションを参照してください。

​

非同期コールバック

OpenAI Images Edits APIが画像を編集するのに時間がかかる可能性があるため、APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費することになります。そのため、本APIは非同期コールバックのサポートも提供しています。

全体の流れは次の通りです：クライアントがリクエストを開始する際に、追加でcallback_urlフィールドを指定します。クライアントがAPIリクエストを開始した後、APIはすぐに結果を返し、現在のタスクIDを示すtask_idフィールド情報を含みます。タスクが完了すると、編集された画像の結果がPOST JSON形式でクライアントが指定したcallback_urlに送信され、その中にもtask_idフィールドが含まれます。これにより、タスク結果をIDで関連付けることができます。

以下の例を通じて、具体的にどのように操作するかを理解しましょう。

まず、WebhookコールバックはHTTPリクエストを受信できるサービスであり、開発者は自分が構築したHTTPサーバーのURLに置き換える必要があります。ここでは、便利なデモのために公開されたWebhookサンプルサイトhttps://webhook.site/を使用します。このサイトを開くとWebhook URLが得られます。以下のように表示されます：

このURLをコピーしてWebhookとして使用できます。このサンプルはhttps://webhook.site/3d32690d-6780-4187-a65c-870061e8c8abです。

次に、フィールドcallback_urlを上記のWebhook URLに設定し、対応するパラメータを入力します。以下のコードのように：

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=これらのアイテムを含む素敵なギフトバスケットを作成する" \
  -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 の接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。