Skip to main content
POST
Image Edit: edit or fuse reference images by instruction
右側のインタラクティブなプレイグラウンドでは、ローカル画像を直接アップロードできます。Authorization に API Key を入力し(形式: Bearer sk-xxx)、画像 / マスクファイルを選択し、promptmodel を入力して、送信してください。
ユースケース: このページは「1枚以上の参照画像に基づく編集 / 融合 / インペイント」向けです。リクエスト形式は multipart/form-data です。純粋な text-to-image には、Text-to-Image エンドポイント を使用してください。
🖥️ ブラウザーのプレイグラウンドの制限(重要)このエンドポイントは、レスポンスとして 生の base64 文字列(通常は数 MB)を返します。ブラウザーのレンダリング制限のため、右側のプレイグラウンドにはレスポンス到着後に 请求时发生错误: unable to complete request が表示される場合があります — リクエスト自体は成功しています。ブラウザーが、そのように長い base64 文字列を表示できないだけです。推奨ワークフロー(初心者向け):
  • 下の Python / Node.js / cURL サンプルをコピーしてローカルで実行してください。コードはレスポンスを自動的に base64.b64decode し、画像をファイルに書き出します。
  • ブラウザー内のプレイグラウンドを使う必要がある場合は、小さな参照画像(< 50KB) を使い、size を最小ティア(例: 1024x1024)に設定し、qualitylow に設定してください。
⚠️ 主な違い(gpt-image-1.5 から移行する場合)
  • input_fidelity は渡さないでくださいgpt-image-2 は高忠実度を強制するため、渡すと 400 が返ります
  • 編集リクエストは input tokens がかなり多くなります — 参照画像は Vision の課金で多くの tokens に変換されるため、予算を見込んでください
  • background: transparent はサポートされていませんopaque を使うか、後処理してください
  • 複数画像の融合: 最大 16 枚image[] フィールドを繰り返し指定してください。16 を超えるとエラーになります
📎 複数画像の融合では順序が重要ですimage[] フィールドは複数の参照画像を受け付けます。アップロード順が、プロンプト内の「image 1 / image 2 / image 3」の参照に対応します。明示的に参照してください:
image 1 の被写体を image 2 のシーンに配置し、image 3 の色スタイルを使う
1ファイルあたりの上限: 各 50MB 未満(multipart ファイルアップロード)、形式: png / jpg / webp; 実際にはアップロード前に 1.5MB 以内 まで圧縮してください(下の「アップロードサイズの上限」を参照)。

コード例

Python (OpenAI SDK · 単一画像編集)

Python (OpenAI SDK · 複数画像融合)

cURL (複数画像融合)

cURL (マスクのインペインティング)

Node.js (ネイティブ fetch + FormData · 複数画像融合)

パラメータリファレンス

レガシーな DALL·E の値 standard / hdquality に渡さないでください。 受け付けられるのは、4つの公式な enum 値 low / medium / high / auto のみです。レガシー値はバックエンドチャネル間で挙動が一貫せず、即座に 400(invalid_value)で失敗することもあれば、黙って無視されてリクエストが auto で実行されることもあります(コストが予測不能になります)。必ず4つの公式値のいずれかを明示的に指定してください。

アップロードサイズの制限

合計リクエストサイズを上限いっぱいまで使わないでください: 画像ごとの上限は 50MB、最大 16 枚までですが、上限に近い画像を複数送ると 1 回のリクエスト本文が非常に大きくなり、ゲートウェイ / CDN / タイムアウトの失敗が起きやすくなります。実運用では、各画像を 1.5MB 以内に圧縮する(JPEG 品質 80-90)と、成功率と生成速度の両方が目に見えて改善し、出力品質は入力ファイルサイズに依存しません。

参照画像の形式要件と前処理

/v1/images/editspng / jpg / webp の標準形式のみを受け付けます。次の 400 が返ってきた場合:
参照画像はおそらく 標準的な JPEG/PNG ではありません。最もよくある落とし穴は、スマホのカメラで生成される MPO 形式(Multi-Picture Object、マルチフレーム JPEG コンテナ)です。.jpg Huawei Mateシリーズの端末からそのまま出力されたファイルには HDR のゲインマップ用サブフレームが埋め込まれており、実際には MPO です。これらのファイルは同じ FFD8 ヘッダーで始まります。拡張子と file コマンドのどちらも JPEG と表示されるため、見た目では判別できません。フレームを認識できるパース(例: Pillow)だけが見分けられます。エラーにある「image 1」は N 番目の参照画像(1 始まり)を指すので、インデックスを使って問題のファイルを特定してください。
2026 年 7 月に検証済み: MPO ファイルは 5/5 のアップロードで 400 になりました。同じ画像を標準の JPEG/PNG に再エンコードすると、元の 3072×4096 のフル解像度のまま成功しました。問題は形式であり、寸法やファイルサイズではありません。このエラーは入力検証段階で素早く(約 4 秒)返され、課金されません
検出と修正: Image.open(f).format"MPO" を返す場合、ファイルの変換が必要です。アップロードパイプラインに 1 回の再エンコード手順を入れておけば、HEIC や他のスマホ形式にも対応できます:
製品がユーザー撮影の写真(室内レンダリング、商品写真など)を受け付ける場合は、画像を 1 枚ずつデバッグするのではなく、サーバー側で一律に再エンコードしてください。スマホの HDR 写真は今後も出てきます。入力処理のヒントは Image API の基本とベストプラクティス をご覧ください。

マスク インペインティング要件

  • 元画像と同じサイズPNG形式4MB未満
  • アルファチャンネル必須: 透明(alpha=0)= インペイント対象領域、不透明 = 保持
  • マスクは最初の画像にのみ適用されます
  • マスクは「ソフトガイド」です — モデルはマスクされた領域の周囲を拡張または縮小する場合があります
マルチターンの反復: 前回の出力を次の呼び出しのimage[]としてフィードバックし、新しい指示で段階的に調整します。各ラウンドは個別に token 課金されます — 累積コストに注意してください。

Response Format

b64_json is raw base64, without the data:image/...;base64, prefix — different from gpt-image-2-all. Decode it client-side to write a file, or prepend the prefix for browser rendering.
Edit requests’ input_tokens are typically significantly higher than text-to-image at the same size, because reference images are billed per Vision pricing rules — the exact amount is available directly in usage.input_tokens_details.image_tokens, tracked separately from the text portion (text_tokens). Multi-image fusion increases image_tokens strictly linearly per additional reference image (verified July 2026: 4 × 1024² images = 4 × 1024 tokens) — see How Multiple Input Images Affect the Price for the measurement table. See How to check the real token count for each call on the overview page for the full field reference.

承認

Authorization
string
header
必須

API Key obtained from APIYI Console

ボディ

multipart/form-data
model
enum<string>
デフォルト:gpt-image-2
必須

Model name, fixed as gpt-image-2

利用可能なオプション:
gpt-image-2
prompt
string
必須

Edit/fusion instruction. For multi-image, use 'image 1 / image 2 / image 3' to reference upload order

:

"Place subject from image 1 into scene from image 2, using color style from image 3"

image
file[]
必須

Reference images. For a single image, send the field once; for multiple images, repeat the same image field (e.g., -F [email protected] -F [email protected], max 16) — upload order maps to image 1 / image 2 / ... in the prompt. multipart file upload: each under 50MB, formats: png/jpg/webp; compress to within 1.5MB in practice

mask
file

Mask image (optional, only applies to first image). Requirements:

  • Same size as original
  • PNG format, under 4MB
  • Must have alpha channel (alpha=0 = inpaint area, opaque = preserve)
size
string
デフォルト:auto

Output size (same as text-to-image). Preset or constraint-satisfying custom size

:

"1536x1024"

quality
enum<string>
デフォルト:auto

Quality tier

利用可能なオプション:
auto,
low,
medium,
high
output_format
enum<string>
デフォルト:png

Output format

利用可能なオプション:
png,
jpeg,
webp
output_compression
integer

Output compression (0–100), only effective for jpeg/webp

必須範囲: 0 <= x <= 100
background
enum<string>
デフォルト:auto

Background mode. auto or opaque. Not supported: transparent

利用可能なオプション:
auto,
opaque

レスポンス

Image generated successfully

created
integer
:

1776832476

data
object[]

Generation results (this model returns 1 image per call)

usage
object

Token usage for this call