> ## Documentation Index > Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt > Use this file to discover all available pages before exploring further. # GPT Imageの1K・2K・4K、Quality、Maskの使い方：BetterToken実測ガイド > BetterTokenのテストに基づき、GPT Imageのサイズ、品質、Mask編集、実際の出力ピクセル、課金区分、価格、API例を解説する実用ガイドです。 export const GptImageComparison = ({kind, labels, caption, label}) => { const comparisonPanels = { crops: [["comparison-crop-1k.png", 480, 480], ["comparison-crop-2k.png", 480, 480], ["comparison-crop-4k.png", 480, 480]], mask: [["comparison-mask-original.png", 476, 476], ["comparison-mask-overlay.png", 476, 476], ["comparison-mask-result.png", 476, 476]], boundary: [["comparison-boundary-original.png", 576, 256], ["comparison-boundary-result.png", 576, 256]], circles: [["comparison-circles-original.png", 416, 416], ["comparison-circles-overlay.png", 416, 416], ["comparison-circles-result.png", 416, 416]] }; const panels = comparisonPanels[kind]; return

{labels.map((title, index) =>

{title}

)} {panels.map(([file, width, height], index) =>

)}

{caption}

; }; `gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`を使って商品画像、広告素材、デザイン案を生成するとき、開発者は次のような悩みに直面することがあります。 * **同じモデル、同じパラメータなのに、呼び出すタイミングによって結果が違うのはなぜか？** * **4Kや指定サイズを渡したのに、縮小された1K画像が返るのはなぜか？** * **`Mask`による部分編集や`quality=high`は本当に適用されているのか？最終的に何を基準に課金されるのか？** 日常的なAPI呼び出しでは、HTTPステータスが`200 OK`かどうかを見るだけでは不十分です。**画像が生成できること、目的のレイアウトに使えること、費用が透明で予測可能であること**の3つを同時に満たす必要があります。開発者がこれら3モデルの実際の挙動を把握できるよう、BetterTokenはゲートウェイ層で**能力に基づくインテリジェントなルーティング、デフォルトパラメータの正規化、不正パラメータの事前遮断、実際に納品されたピクセルに基づく透明な課金**を実装しました。本ガイドは2026年10月19日時点の最新テストデータと価格スナップショットに基づき、実際に生成した画像と請求記録を使って、呼び出し方法、得られる結果、モデルに残る客観的な制約を紹介します。 > **注**：本ガイドでは`gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`を扱います。Nano Bananaシリーズはパラメータと課金体系が異なるため、混同を避けるために別途詳しく説明します。 *** ## 1. 同じモデル・同じパラメータでも結果が異なるのはなぜ？実際の利用では、同じモデル名の背後にあるサービスノードごとに、実能力や安定性が異なることがあります。基本的な1K画像生成のみをサポートする経路もあれば、`2048×2048`、さらには`3840×2160`の高解像度画像を納品できる経路もあります。`quality`の値、参照画像編集、`Mask`マスクへの対応状況もノードによって異なります。プラットフォームがモデル名だけで単純にリクエストを転送すると、「4Kを指定したのに小さな1K画像が返る」「Maskを渡したらエラーになる」「パラメータを何度も調整する」といった問題が頻繁に起こります。そのため、「APIがパラメータを受け付けたか」と「実際にどのような結果が納品されたか」を分けて検証する厳格なテスト基準が必要です。 *** ## 2. どのようにテストしたか：「サポート」の判定基準結論の客観性と信頼性を確保するため、正式版の回帰テストでは**22件の標準テストシナリオ**を設計しました（有効なリクエスト17件で画像18枚を正常に納品し、不正パラメータのシナリオ5件は想定どおり遮断され、課金されませんでした）。さらに、ECでよく使われる商品画像とMask編集のサンプルも生成しました。検証基準は明確です。 1. **元ファイルのピクセルをデコード**：APIの宣言だけを信用せず、納品された各画像の元ファイルをデコードして幅と高さを読み取り、レスポンスの課金区分とアカウントの実際の引き落とし額を照合します。 2. **サイズが目標を満たすか判定**：明示された幅・高さごとに実際のサイズを比較します。実際のサイズが大きければ合格です。**いずれか一辺が目標サイズより5%を超えて小さい場合は不合格**とします（注：この基準はテスト結果を厳格に評価するためのもので、APIがサイズ未達の有効画像を自動的に破棄するという意味ではありません）。サイズを省略するか`auto`を指定した場合、固定キャンバスの目標はないものとして扱います。 3. **パラメータの受付と実際の効果を分けて判定**：エラーがないことは「パラメータが受け付けられた」ことしか示しません。`Mask`が厳密な領域分離を実現するか、`quality=high`に目視できる改善があるかは、最終画像を確認して判定する必要があります。 *** ## 3. 実測で分かったこと：誤解されやすいパラメータは？リクエストパラメータ、実際に納品されたピクセル、最終請求額を並べて比較したところ、開発者が誤解しやすい重要な事実がいくつか分かりました。 | リクエスト条件 | 実際の納品サイズ | 課金区分とCNY単価 | 実測結果と利用上の意味 | | :- | :- | :- | :- | | `gpt-image-2`、`2048x2048`、`quality`省略 | 2048×2048 | 2K、¥0.11 | `quality`を渡さず（デフォルト画質を使用）、今回のリクエストで2K画像を正常に生成しました。 | | `flare`、`2048x2048`、`quality`省略 | 2048×2048 | 2K、¥0.15 | `2048×2048`サイズでの納品を実測確認しました。 | | `sunburst`、`2048x2048`、`quality`省略 | 2048×2048 | 2K、¥0.15 | `2048×2048`サイズでの納品を実測確認しました。 | | `gpt-image-2`、`1024x1024` | **1024×936** | 1K、¥0.035 | 有効な画像は納品されましたが、高さが約8.6%不足し、今回の厳格なサイズ基準には達しませんでした。 | | `flare` / `sunburst`、`1024x1024` | **両方とも1254×1254** | **2K、いずれも¥0.15** | **1Kをリクエストしても1K課金とは限りません**。実際には指定を超える正方形画像が納品され、2K区分で課金されました。 | | `gpt-image-2`、`1536x1024` | 1536×1024 | 1K、¥0.035 | 標準的な縦横比の横長画像も1K課金区分に該当します。 | | `gpt-image-2`、`3840x2160` | **3840×2159** | 4K、¥0.13 | 高さはわずか1ピクセルの差（誤差 \< 0.05%）で、4Kサイズの受け入れ基準を満たしました。 | | `gpt-image-2`、有効なMask + `2048x2048` + `high` | 2048×2048 | 2K、¥0.11 | Mask編集の処理経路は動作しましたが、部分領域を正確に分離できたかは画像を確認する必要があります。 | パラメータ互換性とエラー処理については、次の結果も得られました。 * **デフォルトパラメータの許容性**：`quality`と`size`を省略する場合、`null`を渡す場合、明示的に`"auto"`を指定する場合のいずれも正常に生成できます。 * **4Kの正しい指定方法**：**「4K」は課金区分の概念であり、`4096x4096`の正方形画像をサポートするという意味ではありません。** 4K相当の高解像度画像が必要な場合は、横長サイズの`3840x2160`を使用してください。 * **不正パラメータを課金なしで遮断**：`4096x4096`、`stream=true`、空文字列の`quality=""`、空文字列の`size=""`、`n=0`を渡したテストリクエストはすべて`HTTP 400`エラーとなり、**一切課金されませんでした**。 *** ## 4. BetterTokenが提供するもの：経路ごとの個別対応は不要基盤モデルの複雑なサイズ変動やノード間の差異に対応するため、BetterTokenはゲートウェイ層で4つの処理を行います。経路ごとに個別の調整コードを書く必要はありません。 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モデルの対応状況：どのモデルを呼び、何を指定すればよい？ `gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`の能力設定と実測範囲は次のとおりです。 | 能力項目 | `gpt-image-2` | `gpt-image-2.5-flare` | `gpt-image-2.5-sunburst` | | :- | :- | :- | :- | | **1K画像生成リクエスト** | 対応（実測済み。実サイズは目標と異なる場合があり、`1024×936`や`1254×1254`となることがあります） | 対応（実測済み。今回、より大きい`1254×1254`が返り、2K課金） | 対応（実測済み。今回、より大きい`1254×1254`が返り、2K課金） | | **2K画像生成（`2048x2048`）** | **今回の実測で納品** | **今回の実測で納品** | **今回の実測で納品** | | **4K画像生成（`3840x2160`）** | **今回の実測で横長画像を納品** | ルーティング設定で対応を整合済み | ルーティング設定で対応を整合済み | | **通常の参照画像編集（Maskなし）** | **今回の実測で対応確認**（Maskを省略するか空のMaskを渡すと通常編集として処理） | 単独での利用は未確認（Mask対応だけから通常編集も可能とは判断できません） | 単独での利用は未確認（Mask対応だけから通常編集も可能とは判断できません） | | **Maskによる部分編集** | **今回、2K納品を実測** | 4K Mask編集の対応を設定済み（他の区分は未確認） | 4K Mask編集の対応を設定済み（他の区分は未確認） | | **画質パラメータ（`quality`）** | デフォルト/`auto`/`high`を**すべて実測検証済み** | デフォルト/`auto`は実測済み、`high`はルーティング設定で整合済み | デフォルト/`auto`は実測済み、`high`はルーティング設定で整合済み | *注：表中の「今回の実測で納品」は、本日の回帰テストおよび事例生成で画像と請求サンプルを直接取得したことを指します。「ルーティング設定で対応を整合済み」は、プラットフォームで該当能力の経路設定が完了しているものの、本日の回帰テストで全組み合わせを個別に再リクエストしたわけではないことを指します。* *** ## 6. 実画像のケース2例：実際の仕上がりは？実際の生成品質を示すため、[OpenAI公式の画像プロンプトガイド](https://developers.openai.com/api/docs/guides/image-prompting)にある\*\*「明確な被写体 + 素材の質感 + 光の方向 + 構図とアスペクト比 + 除外条件」\*\*という書き方を参考にし、BetterTokenの実際のAPIで次のEC向けケースを生成しました（元の出力を保持し、後処理はしていません）。 ### ケースA：EC商品撮影、1K / 2K / 4Kのサイズと細部を比較 **シーン設計（中国語での構想）**： > リアルなECスタジオ写真を生成する。コーラルレッドの陶器マグカップ（取っ手は右向き）が薄いグレーの石材カウンターに置かれ、左側に畳んだベージュのリネンクロスがある。カップには白い文字で「BETTER DAY」とはっきり印字されている。左上から柔らかなサイド光を当て、釉薬の微かな反射、リネンの繊維、自然な接地影を残す。カップ全体を中央に収め、背景はシンプルでニュートラルにする。他の物、透かし、追加の文字は入れない。 **実際に使用した英語プロンプト**： ```text theme={null} 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. ``` `gpt-image-2`（`quality="high"`、1回につき1枚）を使用し、上記のプロンプトは一切変更しませんでした。プロンプトに「4K」と書いて高解像度に見せるのではなく、`size`パラメータだけで3段階のサイズをリクエストしました。 | リクエストサイズ（`size`） | 実際の納品サイズ | 実際の課金区分 / 料金 | 1回の所要時間 | | :- | :- | :- | :- | | `1024x1024` | **1254×1254** | **2K / ¥0.11** | 34.35秒 | | `2048x2048` | **2048×2048** | **2K / ¥0.11** | 31.97秒 | | `3840x2160` | **3840×2161** | **4K / ¥0.13** | 24.36秒 | **1. `1024x1024`リクエストの元画像（実際の返却サイズ：`1254×1254`）：** GPT Image 2の商品画像：1024×1024をリクエストし、1254×1254が返却

GPT Image 2の商品画像：1024×1024をリクエストし、1254×1254が返却

**2. `2048x2048`リクエストの元画像（実際の返却サイズ：`2048×2048`）：** GPT Image 2の商品画像：リクエストと実際の納品サイズはいずれも2048×2048

**3. `3840x2160`リクエストの元画像（実際の返却サイズ：`3840×2161`）：** GPT Image 2の横長商品画像：3840×2160をリクエストし、3840×2161が返却

**4. 3サイズの画像から対応部分を元寸法で切り出して比較（カップの文字と素材の細部）：** **実測所見**： * **高い描写完成度**：3枚とも、コーラルレッドの釉薬の反射、右側の取っ手、薄いグレーの石材カウンター、ベージュのリネン繊維、読みやすい白い「BETTER DAY」の文字が表現されています。 * **独立サンプリングによる違い**：生成ごとに独立したサンプリングが行われるため、カップの縦横比、文字の太さ、布の折り方には自然な違いがあります（たとえば4K横長画像では文字が2行に配置されています）。切り出し画像は各画像の実際の細部を示すものであり、構図を厳密に揃えた光学的な鮮明度テストではありません。 * **課金の境界を直接確認**：最初のリクエストは`1024x1024`でしたが、高解像度の正方形画像`1254×1254`が実際に納品されたため、2枚目の`2048×2048`画像と同じ\*\*2K区分（¥0.11）\*\*で課金されました。 *** ### ケースB：商品の部分的な色変更、Maskの実際の効果と制約ケースAの最初の商品画像（`1254×1254`）を入力元画像とし、同じサイズのアルファチャンネル付きMask画像[mask-mug.png](/images/gpt-image-guide/mask-mug.png)を作成しました。**カップ本体の多角形領域だけを透明（再描画可能）にし、取っ手、飲み口の内側、背景は不透明（保持対象）にしています。カップの文字は透明領域内にあり、プロンプトでは保持するよう指示しています。** Mask範囲の図：黒は透明で変更可能な領域、白は不透明で保持する領域

*(注：上図は白黒の可視化イメージです。黒は変更可能な領域、白は保持する領域を表します。APIに実際にアップロードするのは、透明チャンネルを持つ`mask-mug.png`です。)* **シーン設計（中国語での構想）**： > 透明なMask領域内にあるコーラルレッドのカップ本体だけを濃いネイビーブルーに変更する。陶器の質感、光、反射は維持する。白い「BETTER DAY」の文字、赤い取っ手、リネンクロス、カウンター、背景、全体の構図は変えない。物を追加・削除しない。 **実際に使用した英語プロンプト（モデル：`gpt-image-2`、`size="2048x2048"`、`quality="high"`）**： ```text theme={null} 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. ``` **実際の編集結果（`2048×2048`、38.51秒、料金¥0.11）：** GPT Image 2のMask編集結果：本体は濃い青、取っ手は赤のままだが、飲み口の内側も色が変わった

GPT Image 2のMask編集結果：本体は濃い青、取っ手は赤のままだが、飲み口の内側も色が変わった

**保護領域を越えて変更された部分の比較：** **反例：回帰テストでの「2つの円の色が変わった」サンプル（Mask受付 ≠ 正確な領域分離）** **実測所見（制約を明示）**： * **色変更の主目的は達成**：マグカップ本体の外側は濃いネイビーブルーに変わり、陶器のハイライトも保たれました。**Mask外の赤い取っ手、左側のリネンクロス、背景は全体として維持され、Mask内の「BETTER DAY」の文字も読み取れます。** * **厳密なMask境界は不合格（領域外への変更あり）**：飲み口の縁と内側をよく見ると、もともと不透明の保護領域だったコーラルレッドの部分も濃い青に変更されています。さらに極端な幾何図形の「2つの円の色変更」テストでは、マスクされていない右側の円も色が変わりました。 * **利用上の推奨事項**：参照画像とMaskをアップロードする際は、両者のキャンバスサイズを一致させ（変更箇所は透明、保持箇所は不透明）、プロンプトでは「変更する内容」と「保持する内容」の両方を明記してください。ブランドロゴ、パッケージの小さな文字、厳格なエッジ要件を含む工業・商業用途の画像では、**生成後に拡大して保護領域の境界を必ず確認してください**。 *** ## 7. 価格と実際の利用コスト：最終的な課金額は？ BetterTokenは透明な価格設定を重視しています。以下は**2026年10月19日**時点の公開価格スナップショットです（CNYは企業向け人民元アカウント、USDは通常の米ドルアカウントに適用されます。両者は独立した価格であり、リアルタイム為替レートで換算されません）。 | モデル | 1K単価 / 枚 | 2K単価 / 枚 | 4K単価 / 枚 | | :- | :- | :- | :- | | **`gpt-image-2`**（CNY / USD） | ¥0.035 / \$0.0062 | ¥0.11 / \$0.0194 | ¥0.13 / \$0.0229 | | **`gpt-image-2.5-flare`**（CNY / USD） | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | | **`gpt-image-2.5-sunburst`**（CNY / USD） | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | 上記の公開単価で、生成した画像100枚すべてが実際に対応する課金区分で納品されると仮定した場合、100回呼び出しの参考コストは次のとおりです（算術上の推計）。 | モデル | 1K画像100枚のコスト | 2K画像100枚のコスト | 4K画像100枚のコスト | | :- | :- | :- | :- | | **`gpt-image-2`**（CNY / USD） | ¥3.50 / \$0.62 | ¥11.00 / \$1.94 | ¥13.00 / \$2.29 | | **`flare`または`sunburst`**（CNY / USD） | ¥3.50 / \$0.62 | ¥15.00 / \$2.65 | ¥18.00 / \$3.18 | > 💡 **予算計画で重要なのは、「リクエストパラメータ」ではなく「実際に納品された課金区分」を基準に見積もることです！** > > 上記の実測例のとおり、本日`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枚あたりの安さ」だけでは不十分なのはなぜ？複数プラットフォームの画像APIコストを比較する際、開発者は次の3つの費用を考慮してください。 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. すぐにコピーできる呼び出し例 BetterToken API Keyを環境変数`BETTERTOKEN_API_KEY`に保存すれば、以下のコマンドをコピーしてすぐに呼び出せます。 ### 例1：JSONリクエストで高解像度の商品画像を生成（`POST /v1/images/generations`）以下の例では、`gpt-image-2`を呼び出して`2048x2048`の高解像度商品画像を1枚生成します（`model`は`gpt-image-2.5-flare`または`gpt-image-2.5-sunburst`に置き換えられます）。 ```bash theme={null} 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`）元画像`product-1k-0.png`と、同じサイズの透明Mask`mask-mug.png`を用意します（通常の参照画像編集だけを行う場合は、`-F "mask=..."`の行を削除してください）。 ```bash theme={null} 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：実際の納品ピクセルと課金情報を読み取る（レスポンス構造と解析コード） BetterTokenのレスポンスボディには、標準の`data[].b64_json`に加えて、拡張フィールド`bettertoken_image_billing`が含まれます。 ```json theme={null} { "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" } ] } } ``` 以下のPythonコードを使うと、**画像のデコード、実際の形式の判別、サイズの読み取り、請求額の照合**を一度に行えます。 ```python theme={null} 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）](https://developers.openai.com/api/docs/guides/image-prompting) * [OpenAI Cookbook：入力忠実度の高い画像生成・編集の例](https://developers.openai.com/cookbook/examples/generate_images_with_high_input_fidelity) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.