GPT Image 2 / 2.5 画像編集 API

OpenAI generation API guide - Ace Data Cloud

​

1. API Key を取得する

Ace Data Cloud アプリケーション一覧を開き、利用可能なアプリケーションに入り、API Key をコピーします。

​

2. 画像 URL を使用して編集する

元画像：

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://cdn.acedata.cloud/assets/examples/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0-18240dc44b9c.png",
    "prompt": "Keep the mug, tabletop, camera angle, portrait layout, and soft shadow unchanged. Change only the mug color from white to vivid orange and the pale cream background to solid dark navy blue. No text and no logo.",
    "size": "1024x1536"
  }'

成功したレスポンス：

{
  "success": true,
  "task_id": "49848451-c624-4df9-9dc2-494018daaf4c",
  "trace_id": "5ac021c2-2891-4eed-bfcf-4c6668ac1be1",
  "created": 1788831893,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://cdn.acedata.cloud/assets/examples/gpt-image/49848451-c624-4df9-9dc2-494018daaf4c_0-b6d780a732ca.png"
    }
  ],
  "usage": {
    "input_tokens": 775,
    "output_tokens": 1372,
    "total_tokens": 2147
  }
}

これは 2026 年 9 月 8 日に Ace Data Cloud を通じて実際に完了した編集結果です。マグカップはオレンジ色に、背景は濃いネイビーブルーに変わり、元の構図と 1024×1536 のサイズを維持しています：

​

3. ローカル画像をアップロードする

multipart/form-data を使用します：

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a bright modern studio"

image は繰り返し渡すことができ、GPT Image シリーズは最大 16 枚の参照画像をサポートします。JSON リクエスト内の image は単一の URL または URL 配列にでき、ローカルファイルは multipart でアップロードします。

​

モデルと課金方式

モデル	適用シナリオと課金方式
gpt-image-2	デフォルトのリバースチャネル、成功した画像枚数に応じた固定課金
gpt-image-2:reverse	リバースチャネルを明示的に選択、成功した画像枚数に応じた固定課金
gpt-image-2:official	公式 API チャネル、安定性がより高く、実際の Token 使用量に応じて課金
gpt-image-2.5-flare	生成速度を重視、成功した画像枚数に応じた固定課金
gpt-image-2.5-flare:official	公式 API チャネル、安定性がより高く生成速度も重視、実際の Token 使用量に応じて課金
gpt-image-2.5-sunburst	高忠実度と詳細な制御を重視、成功した画像枚数に応じた固定課金
gpt-image-2.5-sunburst:official	公式 API チャネル、安定性がより高く高忠実度と詳細な制御も重視、実際の Token 使用量に応じて課金

公式 API チャネルのページ上の価格はリクエスト前の見積もりであり、最終的にはレスポンス内の実際の Token 使用量および利用記録に基づきます。

​

4. マスクを使用した部分編集

公式 Images Edit インターフェースでは、mask を通じて変更を許可する領域を指定します。Ace Data Cloud の :official モデルは同じ multipart 契約に従います：

• mask は Alpha チャネル付きの PNG である必要があり、サイズは 4MB を超えてはなりません；
• マスクのサイズは最初の image と完全に一致している必要があります；
• Alpha が 0 の透明ピクセルは編集可能であることを示し、不透明ピクセルは保持すべきことを示します；
• 色が白黒のみで透明チャネルがない RGB 画像は、有効なマスクとして使用できません；
• プロンプトでは、期待する完全な画像を説明するとともに、部分的な変更と変更せずに維持する内容を明確にする必要があります。

以下ではまず元画像からマスクを生成します。例では中央の矩形を透明にし、モデルがその領域のみを変更できるようにします：

from PIL import Image, ImageDraw

source = Image.open("input.png").convert("RGBA")
mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
width, height = source.size
draw.rectangle(
    (width // 4, height // 4, width * 3 // 4, height * 3 // 4),
    fill=(0, 0, 0, 0),
)
mask.save("mask.png")

次に、元画像とマスクを一緒にアップロードします：

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer 你的 API Key" \
  -F "model=gpt-image-2:official" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=Keep the composition, lighting, and all objects outside the transparent mask unchanged. Inside the masked area, replace the empty tabletop with a small blue ceramic vase."

OpenAI 公式 Python SDK の images.edit 呼び出し方法をそのまま使用することもできます。base_url を Ace Data Cloud に向けるだけです：

from openai import OpenAI

client = OpenAI(
    api_key="你的 API Key",
    base_url="https://api.acedata.cloud/openai",
)

with open("input.png", "rb") as image, open("mask.png", "rb") as mask:
    result = client.images.edit(
        model="gpt-image-2:official",
        image=image,
        mask=mask,
        prompt=(
            "Keep the composition, lighting, and all objects outside the "
            "transparent mask unchanged. Inside the masked area, replace "
            "the empty tabletop with a small blue ceramic vase."
        ),
    )

print(result.data[0].url)

mask を使用する場合、元画像とマスクは同じ multipart リクエスト内で、それぞれ image=@input.png と mask=@mask.png によりアップロードする必要があります。URL の元画像とローカルのマスクファイルを混在させて渡さないでください。純粋な URL 編集リクエストでは、ローカルの mask ファイルを追加することはサポートされていません。マスクは編集領域を制約しますが、生成モデルは依然としてエッジを自然に融合させる可能性があります。厳密な境界が必要な場合は、明確な Alpha エッジを使用し、変更せずに維持すべき内容をプロンプト内で繰り返し指定してください。

上記の呼び出し方法は、OpenAI Image Edit APIおよびGPT Image 公式 Cookbookのマスク例と一致しています。

​

5. よく使われるパラメータ

フィールド	説明
model	gpt-image-2、gpt-image-2.5-flare（より高速）または gpt-image-2.5-sunburst（より高忠実度かつ高制御）；3つとも対応する :official バリアントを選択でき、gpt-image-2 は :reverse もサポート
image	JSON では単一の URL または最大 16 個の URL の配列を使用；multipart では1つ以上の image ファイルフィールドを使用。mask を使用する場合はローカル画像ファイルをアップロードする必要がある
mask	任意の PNG マスク、multipart ファイルアップロードのみ；Alpha チャンネルを持ち、最初の image と同じサイズで、4MB を超えないこと
prompt	編集指示
size	auto または制限に準拠した WIDTHxHEIGHT
n	1～10；response_format=b64_json の場合は 1 のみサポート
response_format	url または b64_json
callback_url	任意の非同期コールバックアドレス

サイズ規則は生成インターフェースと同じです：幅と高さは 16 の倍数である必要があり、長辺は 3840 を超えず、総ピクセル数は 655,360～8,294,400、アスペクト比は 3:1 を超えません。size を省略するか auto を使用する場合、モデルはプロンプトと最初の参照画像に基づいて画面比率を選択します。

gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst および gpt-image-2:reverse は成功した画像数に応じて課金されます；gpt-image-2:official、gpt-image-2.5-flare:official および gpt-image-2.5-sunburst:official は、テキスト入力、参照画像入力、画像出力の実際の Token に基づいて決済され、最終的には利用記録に準じます。

​

6. 非同期コールバックとトラブルシューティング

長時間タスクでは、リクエストに以下を追加できます：

{
  "callback_url": "https://example.com/webhooks/images"
}

非同期の 200 レスポンスは {"task_id": "..."} です；完了後、最終結果がコールバックされます。同期リクエストでは created と data が返されます。

ステータス	確認
400	画像形式/数、パラメータの組み合わせ、サイズ形式；mask を使用する場合は PNG Alpha チャンネル、4MB 制限、および最初の元画像とサイズが一致しているかを確認
401	API Key と Bearer Header
429	リクエスト頻度
504	非同期コールバックに切り替える

エラーレスポンスには trace_id が含まれます。問題を報告する際はこの ID を提供し、API Key は提供しないでください。

完全なフィールドとリアルタイムの列挙値については、OpenAI Images Edits API ページを参照してください。テキストのみからの画像生成については、GPT Image 2 / 2.5 画像生成 を確認してください。