> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 画像圧縮と出力解像度

> 画像API呼び出しで最も混同されやすい2つの質問、つまり出力解像度を決めるものは何か、そして入力の参照画像を圧縮すると出力がぼやけるのか、を明確にします。

このページは、API から image generation/編集モデルを呼び出す開発者向けです。特に混同されやすい 2 つの疑問、**① 出力画像の解像度は何で決まるのか？ ② 入力の参照画像を圧縮すると、出力はぼやけるのか？** を整理します。結論は、Nano Banana、GPT image、SeeDream、Flux、その他の画像モデルに適用され、特定のプロダクト UI には依存しません。

## まったく別の2つのもの

画像モデルを呼び出すとき、「解像度」は2種類あります。リクエスト内の**互いに独立した2つのフィールド**なので、混同しないでください。

|               | 入力画像の解像度 / 圧縮                                             | 出力画像の解像度                                                   |
| ------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
| 何を指すか         | アップロードする**参照画像 / 編集対象の画像**のサイズ / ピクセル数                    | モデルが**生成する**画像のサイズ / ピクセル数                                 |
| 何で決まるか        | アップロード前に適用する圧縮                                            | リクエスト内の**サイズパラメータ**（`size` / `imageSize` / `aspect_ratio`） |
| リクエスト内のどこにあるか | 画像データフィールド（例: `inline_data.data`、`image[]`、`input_image`） | サイズパラメータフィールド — 画像データとは**まったく無関係**                         |

**一言で言うと**: 圧縮は「入力する画像」に影響し、解像度パラメータは「モデルが出力する画像」を制御します。それぞれ別の役割です。

## 品質を圧縮するのか、寸法を圧縮するのか？ 「圧縮」は実際には何を圧縮しているのか

「圧縮」はざっくり使われますが、画像には独立した 2 種類の「サイズ」があり、それぞれに別の圧縮レバーがあります。

|       | ピクセル寸法（解像度）                       | ファイルサイズ                                                   |
| ----- | --------------------------------- | --------------------------------------------------------- |
| 指すもの  | ピクセルでの幅 × 高さ、例: `4284×5712`       | ディスク/帯域の占有量、例: 4.6 MB                                     |
| 決まる要因 | 撮影/生成時の解像度                        | ピクセル数 × エンコード品質 × 視覚的複雑さ                                  |
| 圧縮の手段 | **リサイズ**: 最長辺を比例的に縮小する — ピクセル数が減る | **再エンコード**: 画質を落とす JPEG/WebP エンコード — ピクセル数は同じで、ファイルは小さくなる |

この 2 つは、かなり釣り合わないことがあります。実例を挙げると（実測値。エンコードによって変わります）:

* iPhone 16 Pro の写真は **4284×5712**（約 2400 万画素 — かなり大きい）ですが、保存時にシステムがすでに効率的な非可逆エンコードを適用しているため、ファイルは **4.6 MB** しかありません。
* 同じ画素数の写真でも、高品質で書き出すと **30 MB** 近くになることがあります。

したがって、「この画像は圧縮が必要か」はピクセル数だけでもファイルサイズだけでも判断できません — それぞれが異なる段階に影響するからです:

* **ピクセル寸法** は、モデルが「見られる」情報量の上限と、デコード/理解コストを決めます；
* **ファイルサイズ** は転送コストを左右します: 約 33% の Base64 膨張、アップロード時間、そして 1 ファイル 20 MB の上限はいずれもバイト数に関わります。

<Tip>
  **実務上の推奨は、順番に両方行うことです**: まずピクセル数を上限に抑え（最長辺を比例的に ≤ 2048px へ縮小）、次に品質を上限に抑えます（0.9 で再エンコード）；そして **トリガーとしてファイルサイズを使います**（1.5 MB を超えるファイルのみ処理する）。上の 4.6 MB の写真なら両方の手順が適用され、4284px の辺は 2048px まで縮小され、その後 quality 0.9 で再エンコードされます — 通常、モデルの理解精度に影響を与えずに 1 MB 未満まで下がります。
</Tip>

## 出力解像度は prompt ではなくサイズパラメータで決まります

これが最も一般的な誤解なので、結論からお伝えします。

<Warning>
  **prompt に「4K」「HD」「ultra-clear」「8K」と書いても、出力が 4K になることはありません。** 実際の出力解像度は **リクエスト内の size パラメータのみに依存します**。prompt が制御するのは「何を描くか」であり、「出力をどれくらい大きくするか」ではありません。
</Warning>

モデルごとに使う size パラメータは異なります。代表例は次のとおりです。

| Model family                                | 出力サイズを制御するパラメータ                                     | 値の形式              | 例                                        |
| ------------------------------------------- | --------------------------------------------------- | ----------------- | ---------------------------------------- |
| **Gemini 画像シリーズ** (例: `gemini-3-pro-image`) | `imageConfig.imageSize` + `imageConfig.aspectRatio` | **Tier 文字列** + 比率 | `imageSize: "4K"`, `aspectRatio: "16:9"` |
| **GPT 画像シリーズ** (gpt-image など)               | `size`                                              | **ピクセル文字列 `WxH`** | `size: "2048x2048"`                      |
| **SeeDream シリーズ**                           | `size`                                              | ピクセル文字列 / tier    | `size: "2048x2048"`                      |
| **Flux シリーズ**                               | `aspect_ratio` or `width` + `height`                | 比率文字列 / ピクセル      | `aspect_ratio: "16:9"`                   |

### 例: gemini-3-pro-image

出力解像度は **`imageSize`** tier で制御されます — **`1K` / `2K` / `4K`**（省略時は `1K` がデフォルトです）— そして `aspectRatio` がフレーム比率を制御します:

```json theme={null}
{
  "contents": [ /* prompt text + input images (if any) */ ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}
```

`imageSize` は、実際に出力解像度を決めるフィールドです。各 ratio + tier は固定のピクセル寸法に対応します。たとえば、1:1 の 1K/2K/4K はおおよそ `1024×1024 / 2048×2048 / 4096×4096` で、16:9 はおおよそ `1376×768 / 2752×1536 / 5504×3072` です。

### GPT image series uses a size pixel string

```json theme={null}
{
  "model": "gpt-image-...",
  "prompt": "...",
  "size": "2048x2048"
}
```

<Tip>
  **要点**: 4K にしたい場合は、size パラメータを対応する tier/ピクセル値（例: `imageSize:"4K"` または `size:"4096x4096"`）に設定してください — **prompt に「4K」と書かないでください**。prompt と size パラメータはリクエスト内の独立した 2 つのフィールドであり、エンジンが prompt から「4K」を解析して解像度を調整することはありません。
</Tip>

<Info>
  一部のモデル（特定の adaptive-output タイプ）は **size パラメータを受け付けません** — 出力解像度はモデル自体が決定します（通常は 1〜1.5K 前後です）。これらのモデルでは、パラメータで 4K を強制することはできず、まして prompt で指定することもできません。各モデルの docs/capability statement を確認してください。
</Info>

<Warning>
  **同じモデルファミリー内でも、サポートされる `imageSize` tiers は異なります。** たとえば Gemini 画像ラインナップでは、`gemini-3-pro-image` は `1K`/`2K`/`4K` をサポートしますが、Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`) は **`1K` のみを受け付けます** — `2K`/`4K` を指定するとエラーになります。モデルを切り替えるときは、同じファミリーの別モデルのパラメータを流用せず、必ずそのモデル固有のサポート tier を確認してください。
</Warning>

## 入力画像を圧縮すると出力のシャープネスは損なわれますか？ 基本的にはありません

結論：**ほとんどのシナリオでは、参照用の入力画像を適度に圧縮しても、出力のシャープネスにほぼ影響はありません。** 理由は3つあります。

1. **出力は再生成されるもので、元画像のアップスケールではありません。**
   モデルは、指定したサイズで**新しい画像を描き直します**。出力解像度は`imageSize`/`size`だけで決まり、入力画像のピクセル数には依存しません。入力が3000pxでも2000pxに圧縮されていても、4Kを選べば4Kの出力になります。

2. **入力の圧縮欄と出力サイズ欄は独立しています。**
   圧縮はリクエスト内の「image data」フィールドの容量やピクセル数を変えるだけで、サイズパラメータのフィールドには**決して触れません**。この2つはリクエスト上で無関係です。

3. **推奨される圧縮は穏やかで、モデルが画像を「見る」のに必要な水準を十分に上回っています。**
   実際には、参照画像を**長辺約2048px、JPEG品質約0.9**まで圧縮しても、モデルが構図、色、スタイル、被写体の詳細を理解するには十分すぎます。これらのモデルは内部で入力画像をエンコードする前に、そもそも適度な解像度までダウンスケールしています。

### 厳密に言うと：境界ケース

**画像間 / 細部編集**のタスクでは、入力の特定領域にある微細なテクスチャや小さな文字を厳密に保持する必要があります。その場合、入力を**圧縮しすぎる**（たとえば長辺を数百pxまで落とす、または品質を0.5未満にする）と、理論上は一部のディテールが失われ、編集が元画像をどれだけ忠実に保てるかに間接的な影響を与える可能性があります。

ただし、「長辺 ≤ 2048px、品質 ≥ 0.85」のような穏やかな基準に従う限り、この影響は実運用では**無視できる**レベルです。より正確に言うと、

> **適度な圧縮**（長辺2048px、品質0.9）→ 出力のシャープネスに**知覚できる影響はありません**；
> 細部編集のシナリオでのみ、**極端な過圧縮**によってディテール損失が起こりえます。

## 入力画像の実用的な圧縮設定

呼び出す前に入力画像を圧縮する場合は、帯域幅を節約しつつ有用な情報を失わない、次の穏当な基準をおすすめします。

| 項目          | 推奨値                        | 注記                                                 |
| ----------- | -------------------------- | -------------------------------------------------- |
| 圧縮のトリガーしきい値 | 元画像 > **1.5 MB**           | 小さな画像は圧縮不要です — そのまま送信してください                        |
| 長辺の上限       | **2048 px**                | 比率を保って等比縮小し、アスペクト比を維持します。小さな画像は **絶対に拡大しない** でください |
| 圧縮品質        | **0.9** (0–1)              | 高品質で、見た目上はほぼロスレスです                                 |
| 出力形式        | **元の形式を維持** (JPG/PNG/WebP) | 強制変換しないでください。透過には PNG/WebP を使ってください                |
| 複数画像の合計サイズ  | **約 6 MB** 未満に抑える          | 複数の参照画像がある場合は、画像ごとの予算を動的に分割します                     |
| 単一ファイルの上限   | **≤ 20 MB**                | アップロードのタイムアウトや拒否を避けるため、まずサイズ超過ファイルを圧縮してください        |

適応的な複数画像の扱い: `per-image target = clamp(total budget ÷ image count, 0.3MB, 1.5MB)`。画像が増えるほど画像ごとの割り当ては小さくし、合計を抑えます。すでに目標内の画像は、そのまま通過させます。

<Tip>
  **フォールトトレランス**: 圧縮はあくまであると便利な機能です。**画像の圧縮に失敗した場合は、元画像にフォールバックして処理を続行してください**。圧縮ステップの失敗を理由に、生成リクエスト全体を中断しないでください。
</Tip>

## 下流のワークフローに渡す生成画像: それらも処理する

APIで生成された画像は、想定より大きいことがよくあります。たとえば Nano Banana Pro の 4K ティアを見てみましょう（実測値。各チャネルのエンコード方式によって異なります）。

| チャネル           | 4K画像1枚あたりの典型的なサイズ |
| -------------- | ----------------- |
| AI Studio チャネル | 約**9 MB**         |
| Vertex チャネル    | 約**18 MB**        |

同じ 4K ティアでも、チャネルが違うとエンコード方式が異なるため、ファイルサイズは 2 倍ほど差が出ることがあります。

生成画像が次のステップの入力になる場合（再編集、複数画像の合成、参照画像など）は、**入力画像と同じ基準で先に圧縮してください**（長辺 2048px、quality 0.9）。そうしないと、18 MB の画像は約 33% の Base64 変換オーバーヘッドで約 24 MB まで膨らみ、リクエストボディや単一ファイルの制限にすぐ達してしまい、アップロードも遅くなります。Base64 の膨張については、[Nano Banana Series Developer Guide](/ja/api-capabilities/nano-banana-dev-guide) をご覧ください。

<Tip>
  下流で使うからといって、必ずしも元の高品質な画像が必要とは限りません。中間のワークフロー画像は「モデルが理解できる」基準まで圧縮してください。最終成果物で 4K が必要な場合は、**最後のステップだけ** 4K で生成し、その前の反復は 1K/2K で行うと、速度とコストの両方で有利です。
</Tip>

生成画像が表示やアーカイブ用途だけで、モデルに戻すことがない場合は、[Nano Banana OSS グループ](/ja/api-capabilities/nano-banana-oss-group) を検討してください。画像は URL として返されるため、Base64 転送のオーバーヘッドを避けられます。

## 画像処理のベストプラクティス

圧縮以外にも、API を呼び出すシナリオでは、アップロード前に次の点を扱っておくとよいです。

* **EXIF の向きをピクセルに焼き込む**: スマートフォンの写真は、ピクセルではなく EXIF Orientation タグに回転情報を保存していることがよくあります。処理パイプラインによってはこのタグを無視するため、モデルには横向き／上下逆さまの画像が見えてしまいます。アップロード前に回転をピクセルへ適用してください（多くの圧縮ライブラリは再エンコード時にこれを自動的に行います）。
* **アップロード前に EXIF のプライバシーメタデータを削除する**: 元の写真には、EXIF に GPS 座標、端末モデル、撮影時刻が含まれていることがよくあります。ユーザー写真をサードパーティの API に送る前にメタデータを削除してください。再エンコードで副次的に削除されることが多いですが、順序に注意が必要です。**先に向きを適用し、その後で削除**してください。
* **フォーマット互換性**: iPhone のデフォルト形式である HEIC/HEIF は、多くの画像 API ではサポートされていません。まず JPEG/PNG に変換してください。透過には PNG/WebP を使い、アニメーション GIF は通常、先頭フレームのみが読み取られます。
* **色空間を sRGB に変換する**: Apple デバイスの写真は、一般的に Display P3 を使用しています。カラープロファイルを無視するパイプラインでは色ずれが発生します。アップロード前に sRGB に変換してください。
* **シナリオごとに転送方法を選ぶ**: 入力側では Base64 が最も信頼性があります。URL（`fileUri`）でのアップロードには厳しい CDN 要件があります。トレードオフについては、[Nano Banana Series 開発者ガイド](/ja/api-capabilities/nano-banana-dev-guide) を参照してください。出力側では、[Nano Banana OSS グループ](/ja/api-capabilities/nano-banana-oss-group) を使って Base64 ではなく URL を受け取ってください。
* **実際に必要な出力ティアを選ぶ**: 納品物が要求していない限り 4K は要求しないでください。生成は遅くなり、ファイルは大きくなり、下流の転送／処理コストも高くなります。まずは 1K/2K で反復し、最終レンダリングのときだけ 4K に切り替えてください。
* **URL 出力は速やかに永続化する**: API が返す画像 URL は期限切れになります。受け取ったらすぐに自分のストレージへ移してください。一時的な URL を永続的なアセットとして扱ってはいけません。

## クイックリファレンス

* **出力解像度 = size パラメータ**（`imageSize` / `size` / `aspect_ratio`）であり、**prompt 内のテキストではありません**。4K が必要ですか？ パラメータを設定してください — prompt に書かないでください。
* `gemini-3-pro-image` は `imageSize` を使い、階層は **1K / 2K / 4K** です（デフォルトは 1K）。GPT image シリーズは `size` ピクセル文字列を使います。
* **入力圧縮と出力解像度は無関係です** — リクエスト内の独立した 2 つのフィールドです。
* **ピクセル寸法とファイルサイズは別物です**: 圧縮 = 先にリサイズ（最長辺 2048px）、次に再エンコード（quality 0.9）; トリガーにはファイルサイズを使ってください（1.5MB 超のみ）。
* **適度な入力圧縮（最長辺 2048px、quality 0.9）は出力のシャープネスに影響しません**; 極端な過圧縮だけが、細かい編集でディテールを失う可能性があります。
* 推奨する入力圧縮: 1.5MB 超のみ圧縮、最長辺 ≤2048px、quality 0.9、元の形式を保持、複数画像の合計 ≤6MB、単一ファイル ≤20MB、失敗時は元のファイルにフォールバック。
* **下流のワークフローに渡す前に生成画像を圧縮してください**: Nano Banana Pro の 4K 画像は 1 枚あたり約 9〜18 MB です（チャネルにより変動） — そのまま返すと簡単に制限に達します。
* **アップロード前に EXIF と形式を処理してください**: 方向情報をピクセルに焼き込み、GPS などのプライバシーメタデータを削除し、HEIC を JPEG に変換し、Display P3 を sRGB に変換します。

## 関連ドキュメント

* [Nano Banana シリーズ開発者ガイド](/ja/api-capabilities/nano-banana-dev-guide)
* [使用フィールドと出力の解説](/ja/api-capabilities/nano-banana-usage-metadata)
* [Gemini 画像 API エラーハンドリングガイド](/ja/api-capabilities/gemini-image-error-handling)