> ## 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 画像編集サービスでは、任意の数の画像と指示を入力し、修正後の画像を出力できます。現在、インターフェースは `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`**：公式チャネルで、安定しており、準拠しています。実際の 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` で生成された科学普及図鑑です：
これを「夜間モード」配色に変更したいと考えています。次のように呼び出すことができます：
```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": "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.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`、`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を使用した呼び出し
```shell theme={null}
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"
```
返される結果は以下の通りです：
```json theme={null}
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
"revised_prompt": "リンゴの上に緑の葉を追加する"
}
]
}
```
編集された画像：
### フォーム + ローカルファイルを使用した呼び出し
```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": "リンゴの上に緑の葉を追加する"
}
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=これらのアイテムを含む素敵なギフトバスケットを作成する'
```
このインターフェースを初めて使用する際には、少なくとも4つの内容を入力する必要があります。1つは`authorization`で、ドロップダウンリストから直接選択できます。もう1つのパラメータは`model`で、`model`はOpenAI公式サイトのモデルカテゴリを選択することを意味します。ここでは主に1種類のモデルがあります。詳細は提供されたモデルを参照してください。もう1つのパラメータは`prompt`で、`prompt`は生成する画像のためのヒントです。最後のパラメータは`image`で、このパラメータは編集する画像のパスを指定する必要があります。編集する画像は以下のようになります：
同じ呼び出し効果のPythonサンプル呼び出しコード：
```python theme={null}
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では、以下のコマンドを使用して環境変数を設定できます：
```shell theme={null}
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モデル](#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](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=これらのアイテムを含む素敵なギフトバスケットを作成する" \
-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 の接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。