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

コード例

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

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

cURL(複数画像融合)

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

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

パラメータリファレンス

quality に旧式の DALL·E 値 standard / hd を渡さないでください。 受け付けられるのは6つの公式列挙値 low / medium / high / xhigh / max / auto のみです(xhigh / max は2つの2.5モデルでのみ利用できます)。旧式の値はバックエンドチャネルによって挙動が一貫しません。400(invalid_value)で直ちに失敗する場合もあれば、暗黙的に無視され、リクエストが auto で実行される場合もあります(コストを予測できません)。必ず公式値のいずれかを明示的に渡してください。

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

合計リクエストサイズを上限いっぱいまで使わないでください: 画像ごとの上限は 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.5-sunburst
必須

Model name. gpt-image-2.5-flare (speed-first) / gpt-image-2.5-sunburst (quality- and editing-first) / gpt-image-2 (previous generation) share the same price and parameters; pin a dated snapshot in production

利用可能なオプション:
gpt-image-2.5-flare,
gpt-image-2.5-sunburst,
gpt-image-2,
gpt-image-2.5-flare-2026-09-08,
gpt-image-2.5-sunburst-2026-09-08
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. xhigh / max are new in 2.5 and rejected by gpt-image-2

利用可能なオプション:
auto,
low,
medium,
high,
xhigh,
max
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