GPT Imageの1K・2K・4K、Quality、Maskの使い方：BetterToken実測ガイド

• 同じモデル、同じパラメータなのに、呼び出すタイミングによって結果が違うのはなぜか？
• 4Kや指定サイズを渡したのに、縮小された1K画像が返るのはなぜか？
• Maskによる部分編集やquality=highは本当に適用されているのか？最終的に何を基準に課金されるのか？

注：本ガイドではgpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburstを扱います。Nano Bananaシリーズはパラメータと課金体系が異なるため、混同を避けるために別途詳しく説明します。

​

1. 同じモデル・同じパラメータでも結果が異なるのはなぜ？

​

2. どのようにテストしたか：「サポート」の判定基準

1. 元ファイルのピクセルをデコード：APIの宣言だけを信用せず、納品された各画像の元ファイルをデコードして幅と高さを読み取り、レスポンスの課金区分とアカウントの実際の引き落とし額を照合します。
2. サイズが目標を満たすか判定：明示された幅・高さごとに実際のサイズを比較します。実際のサイズが大きければ合格です。いずれか一辺が目標サイズより5%を超えて小さい場合は不合格とします（注：この基準はテスト結果を厳格に評価するためのもので、APIがサイズ未達の有効画像を自動的に破棄するという意味ではありません）。サイズを省略するかautoを指定した場合、固定キャンバスの目標はないものとして扱います。
3. パラメータの受付と実際の効果を分けて判定：エラーがないことは「パラメータが受け付けられた」ことしか示しません。Maskが厳密な領域分離を実現するか、quality=highに目視できる改善があるかは、最終画像を確認して判定する必要があります。

​

3. 実測で分かったこと：誤解されやすいパラメータは？

• デフォルトパラメータの許容性：qualityとsizeを省略する場合、nullを渡す場合、明示的に"auto"を指定する場合のいずれも正常に生成できます。
• 4Kの正しい指定方法：「4K」は課金区分の概念であり、4096x4096の正方形画像をサポートするという意味ではありません。 4K相当の高解像度画像が必要な場合は、横長サイズの3840x2160を使用してください。
• 不正パラメータを課金なしで遮断：4096x4096、stream=true、空文字列のquality=""、空文字列のsize=""、n=0を渡したテストリクエストはすべてHTTP 400エラーとなり、一切課金されませんでした。

​

4. BetterTokenが提供するもの：経路ごとの個別対応は不要

1. 能力に基づくインテリジェントなルーティング：モデル、目標サイズ（2K/4Kなど）、画像編集/Maskパラメータの有無に応じて、対応能力を持つ利用可能なサービスを自動的に選択します。
2. 統一インターフェースとパラメータのフォールバック：標準化されたPOST /v1/images/generations（画像生成）とPOST /v1/images/edits（参照画像/Mask編集）インターフェースが、null、auto、省略されたパラメータを自動処理し、不正な入力はゲートウェイ層で直接遮断します。
3. 実サイズと課金明細を透明に返却：画像データとあわせて、レスポンスボディのbettertoken_image_billingフィールドが、画像の**実際にデコードされた幅・高さ（width/height）、課金区分（billing_resolution）、通貨、決済金額（settled_amount）**を返します。
4. 2つの重要な概念を明確に区別：
   • Maskパラメータのサポート ≠ ピクセル単位で正確な領域編集：APIでは参照画像とMaskをアップロードして編集できますが、一部の実測結果ではマスク外の保護領域も変更されました。たとえば、幾何図形の二円テストでは、左側の円を透明にして色変更を指示し、右側の円を不透明にして保護するよう指定しましたが、最終的に左右両方の円の色が変わりました。そのため、Maskパラメータの送信には対応していますが、毎回厳密なピクセル単位の領域分離が実現するとは保証しません。
   • qualityパラメータのサポート ≠ 画質向上幅の保証：APIは"auto"や"high"などのパラメータを受け付け、適切にルーティングします。ただし、画像生成には毎回ランダム性があるため、単一サンプルを根拠にhighで必ず何パーセント画質が上がるとは約束しません。

⚠️ 利用開始前に理解しておくべき2つの実際の制約：

1. 能力に基づくルーティングでも、ピクセルが毎回厳密に固定されるわけではありません：基盤サービスの出力差により、適切なノードにルーティングされても実際の出力ピクセルが変動する場合があります。たとえば本日も、1024x1024のリクエストで1024×936が返った例や、3840x2160のリクエストで3840×2161が返った例がありました。キャンバス比率が業務上きわめて重要な場合は、返却された実際の幅・高さに応じてトリミングや後処理を行ってください。
2. 1Kリクエストでも最終的に1K課金とは限りません：課金システムは、実際に納品された有効画像の仕様に基づいて区分を決定します。本日、2つの2.5モデル（および一部のgpt-image-2）は1024x1024のリクエストに対して、より多くのピクセルを持つ1254×1254を返しました。システムはこれを2K区分と判定し、該当する料金で課金します。

​

5. 3モデルの対応状況：どのモデルを呼び、何を指定すればよい？

​

6. 実画像のケース2例：実際の仕上がりは？

​

ケースA：EC商品撮影、1K / 2K / 4Kのサイズと細部を比較

リアルなECスタジオ写真を生成する。コーラルレッドの陶器マグカップ（取っ手は右向き）が薄いグレーの石材カウンターに置かれ、左側に畳んだベージュのリネンクロスがある。カップには白い文字で「BETTER DAY」とはっきり印字されている。左上から柔らかなサイド光を当て、釉薬の微かな反射、リネンの繊維、自然な接地影を残す。カップ全体を中央に収め、背景はシンプルでニュートラルにする。他の物、透かし、追加の文字は入れない。

Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.

• 高い描写完成度：3枚とも、コーラルレッドの釉薬の反射、右側の取っ手、薄いグレーの石材カウンター、ベージュのリネン繊維、読みやすい白い「BETTER DAY」の文字が表現されています。
• 独立サンプリングによる違い：生成ごとに独立したサンプリングが行われるため、カップの縦横比、文字の太さ、布の折り方には自然な違いがあります（たとえば4K横長画像では文字が2行に配置されています）。切り出し画像は各画像の実際の細部を示すものであり、構図を厳密に揃えた光学的な鮮明度テストではありません。
• 課金の境界を直接確認：最初のリクエストは1024x1024でしたが、高解像度の正方形画像1254×1254が実際に納品されたため、2枚目の2048×2048画像と同じ**2K区分（¥0.11）**で課金されました。

​

ケースB：商品の部分的な色変更、Maskの実際の効果と制約

透明なMask領域内にあるコーラルレッドのカップ本体だけを濃いネイビーブルーに変更する。陶器の質感、光、反射は維持する。白い「BETTER DAY」の文字、赤い取っ手、リネンクロス、カウンター、背景、全体の構図は変えない。物を追加・削除しない。

Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.

• 色変更の主目的は達成：マグカップ本体の外側は濃いネイビーブルーに変わり、陶器のハイライトも保たれました。Mask外の赤い取っ手、左側のリネンクロス、背景は全体として維持され、Mask内の「BETTER DAY」の文字も読み取れます。
• 厳密なMask境界は不合格（領域外への変更あり）：飲み口の縁と内側をよく見ると、もともと不透明の保護領域だったコーラルレッドの部分も濃い青に変更されています。さらに極端な幾何図形の「2つの円の色変更」テストでは、マスクされていない右側の円も色が変わりました。
• 利用上の推奨事項：参照画像とMaskをアップロードする際は、両者のキャンバスサイズを一致させ（変更箇所は透明、保持箇所は不透明）、プロンプトでは「変更する内容」と「保持する内容」の両方を明記してください。ブランドロゴ、パッケージの小さな文字、厳格なエッジ要件を含む工業・商業用途の画像では、生成後に拡大して保護領域の境界を必ず確認してください。

​

7. 価格と実際の利用コスト：最終的な課金額は？

💡 予算計画で重要なのは、「リクエストパラメータ」ではなく「実際に納品された課金区分」を基準に見積もることです！ 上記の実測例のとおり、本日flare、sunburst、gpt-image-2に1024x1024（1K）をリクエストした一部の呼び出しでは、1254×1254の画像が納品されました。この場合、システムは実際の納品物を2Kと判定し、1Kの¥0.035ではなく¥0.15または¥0.11を請求します。flareへの1024x1024リクエスト100回がすべて1254×1254で返った場合、現在の単価で100枚の費用は**¥15.00（算術上の推計）**です。 また、課金区分の判定では目標サイズと妥当な誤差しきい値（例：3840×2159は通常4K、1536×1024は1K）を総合的に考慮します。「長辺が1024を超えるか」だけで業務側に独自の再計算ロジックをハードコードしないでください。決済の基準には、必ずレスポンスボディのbettertoken_image_billingフィールドを使用してください。

​

表面的な「1枚あたりの安さ」だけでは不十分なのはなぜ？

1. 実際の出力が目標サイズに達して初めて価格を比較できます：「4K対応、しかも非常に安い」とうたっていても、実際には縮小された1024画像しか返さないリクエストは、高解像度画像が必要な本番環境では使えません。4K価格の比較対象として有効ではありません。
2. 失敗とやり直しのコストを含める：今回の不正パラメータテストは無料でした。有効な画像が納品されても結果に満足できず、再生成する場合は新しいリクエストとなるため、別途予算に含める必要があります。本ガイドで示した商品画像とMaskのケース画像4枚（生成3枚 + 編集1枚）は、それぞれ1回のリクエストで納品されました。Maskサンプルには上記のとおり領域外の色変更がありました。単価は¥0.11、¥0.11、¥0.13、¥0.11で、4枚の実費合計はわずか¥0.46です。請求記録とアカウントの引き落とし額は完全に一致しました。経路が不安定だったり、パラメータに互換性がなかったりして再生成が必要になると、1枚あたりの表示価格が低くても、使える素材を1枚得るための実質的な総コストは増える可能性があります。
3. 隠れた開発・調整コストを削減：BetterTokenは、統一されたパラメータ規則、能力に基づくインテリジェントなルーティング、実ピクセルと課金フィールドのリアルタイム返却により、サービスごとの個別対応やサイズ・費用情報の集計に必要な開発作業を減らします。

​

8. すぐにコピーできる呼び出し例

​

例1：JSONリクエストで高解像度の商品画像を生成（POST /v1/images/generations）

curl https://bettertoken.ai/v1/images/generations -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
JSON

• サイズ指定に関する注意：4K横長画像が必要な場合は"size"を"3840x2160"に変更してください（"4096x4096"は使用しないでください）。現在有効なサイズは、幅と高さがともに16の倍数、長辺が3840以下、長辺と短辺の比率が3:1以下、総ピクセル数が655,360〜8,294,400である必要があります。
• ファイル形式の判別：リクエストで"output_format": "png"を指定しても、一部の基盤ノードがJPEG形式のバイナリを返すことがあります。画像を保存・処理する際は拡張子を固定せず、ヘッダー（Magic Bytes）から実際の画像形式を判定してください。

​

例2：Multipartで参照画像とMaskを使った部分編集（POST /v1/images/edits）

curl https://bettertoken.ai/v1/images/edits -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product-1k-0.png;type=image/png" \
  -F "mask=@mask-mug.png;type=image/png" \
  -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \
  -F "size=2048x2048" \
  -F "quality=high" \
  -F "n=1" \
  -F "response_format=b64_json"

​

例3：実際の納品ピクセルと課金情報を読み取る（レスポンス構造と解析コード）

{
  "created": 1792398084,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.11",
    "outputs": [
      {
        "index": 0,
        "width": 2048,
        "height": 2048,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.11"
      }
    ]
  }
}

import base64
import io
import json
from pathlib import Path
from PIL import Image  # 需要 Pillow

# 将 API 的 JSON 响应保存为 response.json 后执行。
resp_json = json.loads(Path("response.json").read_text())
if "error" in resp_json:
    raise RuntimeError(resp_json["error"])

billing = resp_json["bettertoken_image_billing"]
outputs = {item["index"]: item for item in billing["outputs"]}
for index, item in enumerate(resp_json["data"]):
    img_bytes = base64.b64decode(item["b64_json"], validate=True)
    with Image.open(io.BytesIO(img_bytes)) as image:
        image.load()
        width, height = image.size
        ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format)
        if ext is None:
            raise ValueError(f"未处理的图片格式：{image.format}")
    Path(f"output_{index}.{ext}").write_bytes(img_bytes)
    info = outputs[index]
    print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}")
    print(f"单张费用：{info['amount']} {info['currency']}")
    if (width, height) != (info["width"], info["height"]):
        print("图片像素与响应尺寸不一致，请保留结果并联系支持。")
print(f"本次结算：{billing['settled_amount']} {billing['currency']}")

• OpenAI公式ドキュメント：画像プロンプトガイド（Image Prompting Guide）
• OpenAI Cookbook：入力忠実度の高い画像生成・編集の例