「Transparent background is not supported for this model」の直し方3つ

エラーは正直で、直し方はモデル ID の一語変更です。 background: "transparent" は一部の画像モデルのデプロイにだけ入っているプレビュー機能で、OpenAI の cookbook が使っているモデルは、ここでは動くほうではありません。

エラー：      400、"Transparent background is not supported for this model."
type：        image_generation_user_error
発生：        openai/gpt-image-2（1.1 秒、生成前）
動く：        openai/gpt-image-1.5（200、RGBA PNG、アルファ 0 が 67.3%）
静かな失敗：  gemini-3-pro-image、qwen-image-3.0、mai-image-2.5-flash
              いずれも 200、いずれもカラータイプ 2、アルファなし
形式の規則：  PNG のみ。jpeg は 400、webp も 400。
プロンプト：  プロンプトがパラメータに勝つ。情景を書けば情景が戻る。
計測：        2026-08-24、POST /v1/images/generations、1024x1024、n=1

刺さる順に、直し方は3つです。

• その1、モデルを替える。 能力はリクエストではなくデプロイに紐づいています。モデル ID を1つ替えれば 200 と本物のアルファチャンネルが返ります。
• その2、出力を PNG のままにする。 jpeg も webp もここでは 400 で、しかも理由が違います。
• その3、プロンプトを書き直す。 プロンプトはパラメータより強く、情景に触れたプロンプトは情景を返してきます。

最終更新 2026-08-24。OpenAI は透過アセットをプレビューと説明しているため、どのモデル ID に能力があるかは変わり得ます。私たちのものを含め、どんなモデル一覧を信じる前にも、この記事の判定手順を再実行してください。

なぜ gpt-image-2 は非対応と言うのか

そのモデル ID の背後にあるデプロイで透過プレビューが有効になっていないからです。 これはパラメータが間違っていることの遠回しな表現ではありません。

返ってくるのはこれで全部です。

{
  "error": {
    "code": null,
    "message": "Transparent background is not supported for this model.",
    "param": null,
    "type": "image_generation_user_error"
  }
}

つまらない説明を2つの事実が否定します。返るのが 1.1 秒なので、生成して捨てたわけではありません。そして同じモデル ID・同じキーで background: "opaque" にすると 200 と普通の画像が返ります。フィールドを握りつぶすゲートウェイなら、同じフィールドの2つの値に別々の結果を出せません。

手順どおりにやっているのに踏むのは、OpenAI の透過画像アセットの cookbook が gpt-image-2 で書かれているからです。ただし冒頭の前提をもう一度読んでください。透過に対応した画像モデルへのアクセスが必要であり、この機能はプレビューだと書かれています。アクセスフラグの後ろに機能がある世界では、モデル名と能力は別物です。

実際に透過 PNG を返すモデルはどれか

試した5つのうち1つ。 同じプロンプト、同じサイズ、同じエンドポイント、同じ日。

危険なのは下半分の3つの 200 です。 400 は無料で、しかも何を変えるべきか教えてくれます。黙って不透明な PNG を返す 200 は、生成1回分の費用を取り、あなたが書いた response.ok のチェックをすべて通過し、1週間後にスライドの白い四角として現れます。

握りつぶしは推測ではなく確認しました。gpt-image-1.5 に background: "bogus" を送ると、正しい値を並べた 400 が返ります。

Invalid value: 'bogus'. Supported values are: 'transparent', 'opaque', and 'auto'.

同じでたらめを gemini-3-pro-image に送ると 200 と画像が返ります。フィールドを検証する経路はゴミを拒否し、ゴミを受け入れる経路はそもそも transparent を尊重する気がありません。

4つの拒否は実際の呼び出しで、最後のブロックはモデルが返したファイルの PNG ヘッダーを読んだものです。

直し方1：どのモデルに替えるか

openai/gpt-image-1.5、他は何も変えません。 gpt-image-2 で落ちるボディがそのまま通ります。

from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.io/v1", api_key="YOUR_OFOX_API_KEY")

resp = client.images.generate(
    model="openai/gpt-image-1.5",   # ここが gpt-image-2 だと 400
    prompt=(
        "A single glossy red ceramic coffee mug, isolated product cutout, "
        "no backdrop, no scene, no shadow, no reflection, transparent background, "
        "no text, no letters, no logos, no watermarks"
    ),
    size="1024x1024",
    background="transparent",
)

カタログのパイプラインに組み込むなら、モデル ID を明示的に固定し、レスポンスにアルファがなければ大きな音で失敗させてください。フォールバックのモデルに一晩で不透明な切り抜きを千枚作らせるより、ずっとましです。同じパイプラインで出る他のエラーは gpt-image-2 の失敗パターンにまとめています。

直し方2：アルファを保持できる出力形式

PNG、そして PNG だけ。 JPEG はアルファチャンネルを保存できず、API は生成前にそう伝えます。WebP は一般にはアルファを保存できますが、このエンドポイントではそもそも選べません。

output_format: "jpeg"  ->  400  Transparent background is not supported for JPEG output format
output_format: "webp"  ->  400  Invalid value: 'webp'. Supported values are: 'png' and 'jpeg'.

2つの拒否は区別する価値があります。JPEG のほうは形式の能力の話で、WebP のほうはこのエンドポイントが受け付ける形式一覧が短いという話です。EC のパイプラインでは効いてきます。WebP を直接もらって変換工程を省きたくなりますが、ここでは PNG を生成して下流で変換します。

直し方3：透過にしたのに背景だらけなのはなぜか

プロンプトがパラメータに勝つからで、しかも大差です。 OpenAI の cookbook は注意書きとして書いています。私たちはそれがいくらの損になるかを測りました。

同じモデル、同じ background: "transparent"、プロンプトだけ2種類。

2枚目は透過機能の失敗ではありません。アルファは確かに出ています。ただし描けと言われた情景の周りに出ただけで、商品カタログには使えませんし、誰も出荷前にファイルを見ないなら使えない以上に有害です。

実務的な規則は、対象だけを描写してから否定語を足すこと。counter、studio、gradient、table、sunset、shadow といった語はすべて背景を呼び戻します。反射を頼むのも同じです。

PNG に本当に透明があるか確かめる方法

1バイト読むだけです。 PNG はカラータイプを IHDR チャンク、ファイルのオフセット 25 に格納しています。

python3 -c "print('colour type', open('out.png','rb').read(26)[25])"
# 6 = トゥルーカラー + アルファ   4 = グレースケール + アルファ
# 2 = トゥルーカラー、アルファなし 3 = インデックス（透明は tRNS チャンクの可能性）

カラータイプは必要条件であって十分条件ではありません。アルファが全ピクセルで 255 の RGBA ファイルは、チャンネルを1つ余分に持った不透明画像で、まさに言葉足らずのプロンプトが返してくるものです。ピクセルを数えましょう。

from PIL import Image

im = Image.open("out.png")
print(im.mode)                                     # アルファがあれば RGBA
if im.mode == "RGBA":
    hist = im.getchannel("A").histogram()
    px = im.width * im.height
    print(f"{100 * hist[0] / px:.1f}% fully transparent")
    print(f"{100 * hist[255] / px:.1f}% fully opaque")

この記事の数値はすべてこの2つの検査から出ています。チャンネル API の残りは Pillow の Image リファレンス、ヘッダーを自分で解析したい場合のカラータイプ表は PNG 仕様にあります。

アルファの検査は CI に入れてください。 あるモデル ID の背後のデプロイが静かに入れ替わっても誰も教えてくれませんが、「完全透明なピクセルが 30% 以上」というテストは教えてくれます。

透過画像1枚のコスト

成功した生成は入力 46 トークン、出力 4,415 トークンで、内訳は画像 4,160、テキスト 255 でした。モデルページのレート、入力 100 万あたり $5、出力画像 $32、出力テキスト $10 で計算すると、1024x1024 の切り抜き1枚で約 $0.136 です。

追いきれなかった点が1つ。同じサイズを gpt-image-2 で background: "opaque" にすると、画像出力トークンは 196 しか報告されませんでした。2つのモデルが桁違いのスケールで画像トークンを報告するということは、メガピクセルあたりのトークンを定数と仮定せず、モデルごとに実測の usage から価格を出すべきだということです。

使いたいモデルに透過機能がない場合

フィールドを落とすモデルに縛られているなら、正直な選択肢が2つと、やってはいけないことが1つあります。

• 単色背景で生成して切り抜く。 被写体に出てこない不自然な単色にしておくと、下流のマット処理がずっと楽になります。遅く、エッジは荒れますが、予測可能です。
• 能力のあるモデルで一度作って使い回す。 透過はファイルの性質であってパイプラインの性質ではありません。よい切り抜き1枚は再レンダー100回に勝ります。
• 不透明で返ってきた 200 を出荷しない。 色付きスライドの上で白い長方形として現れ、気づいたときにはバッチは千枚に達しています。

画像エンドポイントそのものの全体像は Qwen Image 3.0 Pro の実測が表の別系統をカバーしています。Google の画像生成ドキュメントには Gemini 系の画像モデルが何を公開しているかが載っているので、機能の欠落をルーティングの問題と決めつける前に読む価値があります。

参考資料

• OpenAI cookbook: 透過画像アセット
• OpenAI: 画像生成ガイド
• W3C: PNG 仕様、IHDR カラータイプ
• Pillow: Image リファレンス
• Google: Gemini API 画像生成
• ofox モデルページ: GPT Image 1.5
• ofox モデルページ: GPT Image 2