> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAI Images Edits API 申請及使用
> OpenAI generation API guide - Ace Data Cloud
OpenAI 画像編集サービスでは、任意の数の画像と指示を入力し、修正後の画像を出力できます。現在、インターフェースは `dall-e-2`、`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 コントロールセンター](https://platform.acedata.cloud/console/applications) にアクセスして、API トークンを取得し、保管しておきます。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コントロールセンター](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全な文書：[OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits)
## 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`**：公式中継ルート。`n > 1`（一度に複数の画像を返す）および実際の 2K / 4K をサポートし、**各画像ごとに課金され、単価はデフォルトの `gpt-image-2` の 2 倍です**。現在、openai-hk チャンネルのみが提供しており、ルートが利用できない場合は直接エラーを返し、逆向きのルートにはダウングレードされません。
* **`gpt-image-2:reverse`**：デフォルトの `gpt-image-2` と完全に同等（逆向きのルート）で、価格は変わりません。
> 以下の「`n` パラメータに関する制限」はデフォルト / 逆向きのルートにのみ適用されます；`gpt-image-2:official` は `n > 1` をサポートし、画像ごとに課金されます。
### サポートされている `size` の値
編集インターフェースの `size` に対する制約は生成インターフェースと完全に一致します——`gpt-image-2` は `size` が `auto`、空、または `WIDTHxHEIGHT` 形式に合致する限り、他の形態は 400 を返します。**すべてのサイズ（1K / 2K / 4K / カスタム）は単一の画像ごとに統一して課金され、元画像の解像度や `size` リクエスト値には関係ありません。**
上流のカスタムサイズに対する厳格な制約も同様に適用されます：幅と高さは両方とも 16 の倍数、長辺 ≤ 3840、総ピクセル数 ≤ 8,294,400。
| 比率 | 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` を指定するか省略すると、モデルが自動的に選択します。3つの料金は同じです。
> **`n` パラメータについて**
> `gpt-image-2` 編集インターフェースは現在\*\*`n > 1` をサポートしていません\*\*：このパラメータは静かに無視され、`n=1` または `n=10` を指定しても、単一のリクエストで返されるのは 1 枚の画像のみで、1 枚分の料金のみが課金されます。複数の候補編集結果を一度に取得する必要がある場合は、**自分で並行して複数のリクエストを発行してください**。この制限は `gpt-image-1` / `gpt-image-1.5`、および `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` シリーズにも適用されます。`dall-e-2` は現在唯一、原生的に `n > 1` をサポートする編集モデルです。
以下に、2つの異なる方向からの実際の例を通じて `gpt-image-2` の編集能力を体感します。
### 呼び出し方法一：JSON + 画像 URL（推奨）
直接 `application/json` 方式でリクエストを送信し、`image` フィールドに画像の URL を入力します。モデルはその画像を取得し、`prompt` に従って編集を行います。
例えば、以下の画像は `gpt-image-2` で生成された科学普及図鑑です：
私たちはこれを「夜間モード」配色に変更したいと考えています。次のように呼び出すことができます：
```shell theme={null}
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": "このインフォグラフィックをダークモードに変換してください：ダークネイビーの背景、ライトクリームのテキスト、柔らかい影のある深いグレーの丸みを帯びたモジュールカード。すべてのレイアウト、構造、モジュールの配置を同じに保ち、色のスキームだけを反転させてください。",
"size": "1024x1536"
}'
```
またはPythonを使用：
```python theme={null}
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)
```
返された結果は以下の通りです：
```json theme={null}
{
"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でも構いません。これは、ローカル画像を先にアップロードしたくない場合に適しています。例えば：
>
> ```python theme={null}
> 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` は複数の画像を同時に参照して最終結果を生成することができます。例えば、複数の製品写真を一つのギフトバスケットに合成する場合：
```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": "上記のすべてのアイテムをクリーンな白い背景の上にある単一の「リラックス＆リワインド」ギフトバスケットにまとめてください。フォトリアルで、柔らかい自然光を使用してください。",
"size": "1024x1024"
}
```
### シーンの例：スタイルを変更 + 構造を保持
以下は別の例で、木製の本棚を現代的な浮き棚に置き換えますが、各段の本の数と配置は厳密に保たれます。
元の画像（`gpt-image-2` で生成された木製の本棚）：
呼び出し：
```python theme={null}
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` に変更するだけです：
```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="この画像をダークモードに変換し、レイアウトをそのまま保ってください。"
)
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` を取得したトークンに設定します：
```shell theme={null}
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`。
>
> * `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.acedata.cloud/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.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"
```
返される結果は以下の通りです：
```json theme={null}
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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つの内容を入力する必要があります。一つは `authorization` で、ドロップダウンリストから選択できます。もう一つのパラメータは `model` で、`model` は OpenAI の公式モデルカテゴリを選択するものです。ここでは主に1種類のモデルがあります。詳細は提供されたモデルを参照してください。もう一つのパラメータは `prompt` で、`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.acedata.cloud/openai` に設定できます。もう一つは認証変数 `OPENAI_API_KEY` で、この値は `authorization` から取得したものです。Mac OSでは以下のコマンドで環境変数を設定できます：
```shell theme={null}
export OPENAI_BASE_URL=https://api.acedata.cloud/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 リクエストを発行した後、API はすぐに結果を返し、現在のタスク ID を示す `task_id` フィールド情報を含みます。タスクが完了すると、編集された画像の結果が POST JSON 形式でクライアントが指定した `callback_url` に送信され、その中にも `task_id` フィールドが含まれます。これにより、タスク結果を ID で関連付けることができます。
以下の例を通じて、具体的にどのように操作するかを理解しましょう。
まず、Webhook コールバックは HTTP リクエストを受信できるサービスであり、開発者は自分が構築した HTTP サーバーの URL に置き換える必要があります。ここではデモのために、公開の Webhook サンプルサイト [https://webhook.site/](https://webhook.site/) を使用します。このサイトを開くと、Webhook URL が得られます。以下のように表示されます：
この URL をコピーすれば、Webhook として使用できます。ここでのサンプルは `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab` です。
次に、フィールド `callback_url` を上記の Webhook URL に設定し、以下のコードのように対応するパラメータを入力します：
```shell theme={null}
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=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 の接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。