> ## 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.

# Сжатие изображений и выходное разрешение

> Разъясняет два вопроса, которые чаще всего путают в вызовах image API: что определяет выходное разрешение и делает ли сжатие входных reference images выходное изображение размытым?

Эта страница предназначена для разработчиков, которые вызывают модели генерации/редактирования изображений через API. Она проясняет два наиболее часто путаемых вопроса: **① Что определяет разрешение выходного изображения? ② Делает ли сжатие входных референсных изображений выход размытым?** Выводы применимы к Nano Banana, GPT изображения, SeeDream, Flux и другим моделям изображений, независимо от какого-либо конкретного интерфейса продукта.

## Две совершенно разные вещи

При вызове image model есть два «разрешения». Это **два независимых поля** в запросе — не путайте их:

|                             | Разрешение входного изображения / сжатие                                                            | Разрешение выходного изображения                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| К чему это относится        | Размер/пиксели **референсного изображения / изображения для редактирования**, которое вы загружаете | Размер/пиксели изображения, которое **генерирует** модель                |
| Что это определяет          | Сжатие, которое вы применяете перед загрузкой                                                       | **Параметр размера** в запросе (`size` / `imageSize` / `aspect_ratio`)   |
| Где это находится в запросе | Поля данных изображения (например, `inline_data.data`, `image[]`, `input_image`)                    | Поле параметра размера — **совершенно не связано** с данными изображения |

**Одной фразой**: сжатие влияет на «изображение, которое вы подаете на вход»; параметр разрешения управляет «изображением, которое модель выдает на выход». У каждого — свои задачи.

## Сжатие качества или сжатие размеров? Что именно сжимает «компрессия»

«Compression» часто используют в широком смысле, но у изображения есть два независимых вида «размера», и у каждого свой рычаг сжатия:

|                    | Размеры в пикселях (разрешение)                                                          | Размер файла                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Что это означает   | Ширина × высота в пикселях, например `4284×5712`                                         | Занимаемый объем на диске/в полосе пропускания, например 4.6 MB           |
| Что это определяет | Разрешение в момент захвата/генерации                                                    | Количество пикселей × качество кодирования × визуальная сложность         |
| Рычаг сжатия       | **Изменение размера**: пропорционально уменьшить самую длинную сторону — меньше пикселей | **Перекодирование**: с потерями в JPEG/WebP — те же пиксели, меньший файл |

Эти два параметра могут сильно расходиться. Реальный пример (эмпирические значения; зависят от кодирования):

* Фотография с iPhone 16 Pro имеет размер **4284×5712** (около 24 мегапикселей — очень много), но файл всего **4.6 MB**, потому что система уже применила эффективное кодирование с потерями при сохранении;
* Фотография с тем же количеством пикселей, экспортированная в высоком качестве, может достигать **30 MB**.

Поэтому по одному только числу пикселей или по одному только размеру файла нельзя судить, «нужно ли сжимать» изображение — это разные этапы:

* **Размеры в пикселях** задают верхнюю границу того, сколько информации модель может «увидеть», и стоимость декодирования/понимания;
* **Размер файла** влияет на стоимость передачи: примерно 33% раздувание из-за Base64, время загрузки и ограничение в 20 MB на один файл относятся именно к байтам.

<Tip>
  **Практическая рекомендация — делать и то и другое, по порядку**: сначала ограничьте число пикселей (уменьшите самую длинную сторону пропорционально до ≤ 2048px), затем ограничьте качество (перекодируйте с качеством 0.9); и **используйте размер файла как триггер** (обрабатывайте только файлы больше 1.5 MB). Указанная выше фотография 4.6 MB пройдет оба шага: сторона 4284px уменьшится до 2048px, затем произойдет перекодирование с качеством 0.9 — файл обычно становится меньше 1 MB без влияния на то, насколько хорошо модель его понимает.
</Tip>

## Разрешение вывода задается параметром размера, а не prompt

Это самое распространенное заблуждение, поэтому сначала вывод:

<Warning>
  **Если написать в prompt "4K", "HD", "ultra-clear" или "8K", это НЕ сделает вывод 4K.** Фактическое разрешение вывода **зависит только от параметра размера в запросе**. prompt управляет тем, "что рисовать", а не тем, "какого размера будет вывод".
</Warning>

Разные модели используют разные параметры размера. Наиболее распространенные:

| Семейство моделей                                       | Параметр, управляющий размером вывода               | Формат значения                     | Пример                                   |
| ------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- | ---------------------------------------- |
| **Серия Gemini image** (например, `gemini-3-pro-image`) | `imageConfig.imageSize` + `imageConfig.aspectRatio` | **Строка уровня** + соотношение     | `imageSize: "4K"`, `aspectRatio: "16:9"` |
| **Серия GPT image** (gpt-image и т. д.)                 | `size`                                              | **Строка пикселей `WxH`**           | `size: "2048x2048"`                      |
| **Серия SeeDream**                                      | `size`                                              | Строка пикселей / уровень           | `size: "2048x2048"`                      |
| **Серия Flux**                                          | `aspect_ratio` или `width` + `height`               | Строка соотношения сторон / пиксели | `aspect_ratio: "16:9"`                   |

### Пример: gemini-3-pro-image

Он управляет разрешением вывода через уровень **`imageSize`** — **`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` — это поле, которое фактически определяет разрешение вывода. Каждая комбинация соотношения сторон и уровня сопоставляется с фиксированными размерами в пикселях — например, 1:1 на 1K/2K/4K это примерно `1024×1024 / 2048×2048 / 4096×4096`, а 16:9 — примерно `1376×768 / 2752×1536 / 5504×3072`.

### Серия GPT image использует строку размера в пикселях

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

<Tip>
  **Важный момент**: если вам нужен 4K, задайте параметр размера в соответствии с нужным уровнем/пикселями (например, `imageSize:"4K"` или `size:"4096x4096"`) — **не пишите "4K" в prompt**. prompt и параметр размера — это два независимых поля в запросе; движок не извлекает "4K" из prompt, чтобы изменить разрешение.
</Tip>

<Info>
  Некоторые модели (отдельные типы с адаптивным выводом) **не принимают параметр размера** — разрешение вывода определяется самой моделью (обычно около 1–1.5K). Для таких моделей 4K нельзя принудительно задать через параметры, не говоря уже о prompt. Проверьте документацию/описание возможностей каждой модели.
</Info>

<Warning>
  **Поддерживаемые `imageSize` уровни также различаются внутри одного семейства моделей.** Например, в линейке Gemini image, `gemini-3-pro-image` поддерживает `1K`/`2K`/`4K`, но Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`) **принимает только `1K`** — передача `2K`/`4K` возвращает ошибку. При переключении моделей всегда проверяйте поддерживаемые именно этой моделью уровни вместо повторного использования параметров другой модели из того же семейства.
</Warning>

## Ухудшает ли сжатие входного изображения резкость результата? В основном нет

Вывод: **в подавляющем большинстве сценариев разумное сжатие входных референсных изображений почти не влияет на резкость результата.** Три причины:

1. **Результат пересоздаётся, а не является увеличенной версией вашего изображения.**\
   Модель **создаёт новое изображение** в заданном вами размере. Разрешение результата зависит только от `imageSize`/`size`, а не от того, сколько пикселей было у входного изображения. Неважно, было ли входное изображение 3000px или сжато до 2000px: если вы выберете 4K, вы получите 4K.

2. **Поле сжатия входа и поле размера результата независимы.**\
   Сжатие меняет только объём/количество пикселей в поле "image data" в запросе — оно **никогда не затрагивает** поле параметра размера. Эти два поля в запросе не связаны.

3. **Рекомендуемое сжатие мягкое — значительно выше того, что модели нужно, чтобы "видеть" изображение.**\
   На практике сжатие референсного изображения до **длинной стороны примерно 2048px при JPEG quality около 0.9** более чем достаточно, чтобы модель поняла композицию, цвета, стиль и детали объекта — эти модели всё равно внутренне уменьшают входные изображения до умеренного разрешения перед кодированием.

### Чтобы быть строгими: пограничный случай

В задачах **image-to-image / тонкой правки** (когда нужно строго сохранить мелкие текстуры или небольшой текст в конкретной области входа) слишком агрессивное сжатие входа (например, уменьшение длинной стороны до нескольких сотен пикселей или quality ниже 0.5) теоретически может привести к потере части деталей и косвенно повлиять на то, насколько точно правка сохраняет оригинал.

Но если вы придерживаетесь мягкого стандарта вроде "длинная сторона ≤ 2048px, quality ≥ 0.85", этот эффект в реальной работе **незначителен**. Более точная формулировка:

> **Разумное сжатие** (длинная сторона 2048px, quality 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>

## Сгенерированные изображения, поступающие в последующий workflow: обрабатывайте их тоже

Изображения, создаваемые API, часто больше, чем вы ожидаете. Возьмем 4K-уровень Nano Banana Pro в качестве примера (эмпирические значения; зависят от кодирования в каждом канале):

| Канал           | Типичный размер одного 4K-изображения |
| --------------- | ------------------------------------- |
| Канал AI Studio | \~**9 MB**                            |
| Канал Vertex    | \~**18 MB**                           |

Один и тот же 4K-уровень, но разные каналы кодируют по-разному — размер файла может отличаться в 2 раза.

Если сгенерированное изображение становится входом следующего шага (повторное редактирование, объединение нескольких изображений, reference image), **сначала сжимайте его по тому же стандарту, что и входные изображения** (длинная сторона 2048px, quality 0.9). Иначе изображение размером 18 MB после накладных расходов Base64 примерно на \~33% раздуется до около 24 MB — что легко упирается в лимиты на тело запроса/один файл и замедляет загрузку. См. [Руководство разработчика Nano Banana Series](/ru/api-capabilities/nano-banana-dev-guide) для подробностей о раздувании Base64.

<Tip>
  Использование в последующей обработке ≠ необходимость в нетронутом оригинале. Сжимайте промежуточные изображения workflow до стандарта «модель может это понять»; если итоговый результат требует 4K, генерируйте 4K **только на последнем шаге** — на промежуточных этапах используйте 1K/2K ради скорости и стоимости.
</Tip>

Если сгенерированное изображение нужно только для отображения/архивации и никогда не возвращается в модель, рассмотрите [Nano Banana OSS Group](/ru/api-capabilities/nano-banana-oss-group): изображения возвращаются как URL, что позволяет избежать накладных расходов на передачу Base64.

## Дополнительные рекомендации по обработке изображений

Помимо сжатия, перед загрузкой в сценариях вызова API стоит учитывать следующее:

* **Встраивайте ориентацию EXIF в пиксели**: фотографии с телефона часто хранят сведения о повороте в теге EXIF Orientation, а не в самих пикселях. Некоторые конвейеры обработки игнорируют этот тег, поэтому модель видит изображение, повернутое набок или вверх ногами. Примените поворот к пикселям перед загрузкой (большинство библиотек сжатия делают это автоматически при повторном кодировании).
* **Удаляйте приватные метаданные EXIF перед загрузкой**: оригинальные фотографии часто содержат координаты GPS, модель устройства и время съемки в EXIF. Удаляйте метаданные перед отправкой пользовательских фотографий в сторонний API — повторное кодирование обычно делает это как побочный эффект, но следите за порядком: **сначала примените ориентацию, затем удалите метаданные**.
* **Совместимость форматов**: формат HEIC/HEIF по умолчанию на iPhone не поддерживается большинством image API — сначала конвертируйте в JPEG/PNG; используйте PNG/WebP для прозрачности; у анимированных GIF обычно считывается только первый кадр.
* **Конвертируйте цветовое пространство в sRGB**: фотографии устройств Apple часто используют Display P3. Конвейеры, которые игнорируют цветовой профиль, будут давать сдвиги цветов — перед загрузкой конвертируйте в sRGB.
* **Выбирайте способ передачи под сценарий**: на входной стороне Base64 — самый надежный вариант; загрузка по URL (`fileUri`) требует строгих условий CDN — см. [Руководство разработчика серии Nano Banana](/ru/api-capabilities/nano-banana-dev-guide), чтобы оценить компромиссы. На выходной стороне используйте [Nano Banana OSS группу](/ru/api-capabilities/nano-banana-oss-group), чтобы получать URL вместо Base64.
* **Выбирайте нужный вам уровень выходных данных**: не запрашивайте 4K, если результат этого не требует — генерация будет медленнее, файлы больше, а последующая передача и обработка дороже. Сначала итеративно работайте в 1K/2K и переходите к 4K только для финального рендера.
* **Своевременно сохраняйте URL-выходы**: URL изображений, возвращаемые API, истекают. Переносите их в свое хранилище сразу после получения — никогда не воспринимайте временный URL как постоянный ресурс.

## Краткая справка

* **Выходное разрешение = параметр размера** (`imageSize` / `size` / `aspect_ratio`), **а не текст в prompt**. Нужен 4K? Укажите параметр — не пишите это в prompt.
* `gemini-3-pro-image` использует `imageSize` с уровнями **1K / 2K / 4K** (по умолчанию 1K); серия изображений GPT использует строку пикселей `size`.
* **Сжатие входных данных и выходное разрешение не связаны** — это два независимых поля в запросе.
* **Размеры в пикселях и размер файла — это разные вещи**: сжатие = сначала изменить размер (длинная сторона 2048px), затем перекодировать (quality 0.9); используйте размер файла как триггер (только выше 1.5MB).
* **Разумное сжатие входных данных (длинная сторона 2048px, quality 0.9) не влияет на четкость выхода**; только экстремальное чрезмерное сжатие может привести к потере деталей при тонком редактировании.
* Рекомендуемое сжатие входных данных: сжимайте только выше 1.5MB, длинная сторона ≤2048px, quality 0.9, сохраняйте исходный формат, общий размер нескольких изображений ≤6MB, один файл ≤20MB, при сбое используйте исходный файл.
* **Сжимайте сгенерированные изображения перед передачей их в downstream workflows**: изображение Nano Banana Pro 4K занимает примерно 9–18 MB на изображение (зависит от канала) — если отправлять его как есть, лимиты легко будут превышены.
* **Обрабатывайте EXIF и формат перед загрузкой**: встраивайте ориентацию в пиксели, удаляйте GPS и другие метаданные, связанные с конфиденциальностью, преобразуйте HEIC в JPEG, преобразуйте Display P3 в sRGB.

## Связанные документы

* [Руководство разработчика по серии Nano Banana](/ru/api-capabilities/nano-banana-dev-guide)
* [Поля использования и объяснение вывода](/ru/api-capabilities/nano-banana-usage-metadata)
* [Руководство по обработке ошибок Gemini Image API](/ru/api-capabilities/gemini-image-error-handling)