インペインティング

マスクで範囲を指定し、その部分だけを描き直します。それ以外の部分は元のまま残ります。

コードを書かない場合は、手持ちのツールで画像生成を参照してください。

POST/v1/images/edits共通パラメーター

始める前に

必要なもの	詳細
API キー	OfoxAI コンソールで作成し、コード内の `YOUR_OFOX_API_KEY` を置き換えてください
実行環境	cURL では画像のデコードに `jq` が必要です。Python では `pip install openai` が必要で、マスクの生成には `pip install pillow` も必要です。Node.js は 18 以上で、依存パッケージは不要です
画像	カレントディレクトリに `input.png` と、同じサイズの `mask.png` を置いてください。マスクがない場合は、下記のステップ 1 で作成方法を説明しています
タイムアウト	クライアントのタイムアウトを 600 秒に設定してください。高品質・大サイズ・編集では数分かかる場合があります

コードで使用する値

API URLhttps://api.ofox.io/v1

モデル IDopenai/gpt-image-2.5-flare

API キーコード内の YOUR_OFOX_API_KEY をご自身のキーに置き換えてください

Python の依存パッケージpip install openai pillowpillow はマスクの作成に使用します

マスクの要件

元の画像

マスク中央は透明、それ以外は不透明

→

結果透明な部分だけが描き直される

イメージ図であり、実際の生成結果ではありません

アルファチャンネル付きの PNG。JPEG や不透明な PNG は使用できません。
元の画像と完全に同じサイズ。
透明なピクセルは描き直され、不透明なピクセルは元の画像が残ります。
編集エンドポイントでのみ有効です。テキストからの生成に送ると無視されます。

手順

マスクを作成する

すでにマスクがある場合は、このステップを省略してください。

このスニペットはカレントディレクトリの input.png を読み込み、中央 40% の正方形を透明にして mask.png として保存します。

make_mask.py


from PIL import Image, ImageDraw
 
src = Image.open("input.png")
mask = Image.new("RGBA", src.size, (0, 0, 0, 255))          # 完全に不透明 = すべて保持
w, h = src.size
ImageDraw.Draw(mask).rectangle(                              # 透明な部分 = 描き直される部分
    (int(w * 0.3), int(h * 0.3), int(w * 0.7), int(h * 0.7)), fill=(0, 0, 0, 0)
)
mask.save("mask.png")

リクエストを送信する

以下のコード例はすべてそのまま実行して動作を確認しています。結果はカレントディレクトリに output.png として保存されます。

cURL

Terminal


# mask.png:input.png と同じサイズでアルファチャンネル付き。透明な部分 = 描き直される部分
curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=中央に座っているオレンジ色の猫。背景とその他の部分はそのまま" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

プロンプトの書き方

追加したいものだけでなく、描き直した後の画像全体を説明してください。

	プロンプト	実測結果
✅	中央に座っているオレンジ色の猫。背景とその他の部分はそのまま	中央に猫が描かれ、それ以外は変化なし
❌	透明な部分に猫を描いて	モデルが「透明」を画像の内容として解釈し、市松模様の背景を描いた

実測結果

マスクの外側はほとんど変化しません。元の画像との平均ピクセル差は 2/255 未満でした。

比較として、同じ画像をマスクなしで編集した場合、同じ領域の差は 120/255 でした。

トラブルシューティング

症状	原因	対処法
`Invalid image file or mode` エラー	マスクがアルファチャンネル付きの PNG ではない	上記ステップ 1 のコードで作成し直してください
画像全体が変わった	マスクが効いていない：テキストからの生成エンドポイントに送信したか、マスクが完全に不透明	`/v1/images/edits` を呼び出していること、マスクに透明な部分があることを確認してください
市松模様の背景が描かれた	プロンプトで「透明な部分」に言及した	プロンプトの書き方のとおり、画像全体を説明してください

その他のエラーはエラー一覧を参照してください。

公式ドキュメント

OpenAI のドキュメントは、OpenAI に直接呼び出した場合の動作を説明しています。OfoxAI 経由で呼び出す場合は、このシリーズの実測結果が優先されます。たとえば、編集時にプロバイダーを指定する必要はありません。