> ## 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.
# Генерация и редактирование изображений Nano Banana 2.1
> Google Nano Banana 2.1 (gemini-nano-banana-2.1) в общем доступе: обновление Nano Banana 2 с улучшенным качеством изображений, отрисовкой текста и согласованностью в многошаговых диалогах. $0.05 за запрос (включая 4K) или с оплатой за tokens: $0.66 за ввод / $13.2 за вывод за 1M tokens.
## Обзор
**Nano Banana 2.1** — это модель генерации изображений, выпущенная Google 6 октября 2026 года. Идентификатор модели — **`gemini-nano-banana-2.1`**, и она была запущена в статусе общей доступности (GA). Это обновление для [Nano Banana 2](/ru/api-capabilities/nano-banana-2-image/overview) (`gemini-3.1-flash-image`): она сохраняет скорость уровня Flash, улучшая при этом качество изображений, рендеринг текста внутри изображений и согласованность при многоэтапном редактировании, а также устраняет артефакты тайлинга предыдущей версии. Google рекомендует версию 2.1 для всех новых проектов.
**🆕 Релиз 6 октября 2026 года**: Уже доступно на APIYI с двумя вариантами тарификации: **за запрос** (\$0.05 за запрос, одинаковая цена для 1K / 2K / 4K) и **по токенам** (\$0.66 за входные / \$13.2 за выходные на 1M tokens). Nano Banana 2 по-прежнему доступна по той же цене, и Google не объявляла дату прекращения её поддержки.
Все API для работы с изображениями являются **синхронными** — здесь нет task ID для опроса, и в случае отключения вашего клиента результат будет потерян, тогда как запрос всё равно будет протарифицирован. Задайте достаточно большой таймаут для этой модели; подробнее см. в руководстве [Основы и лучшие практики Image API](/ru/api-capabilities/image-api-best-practices).
Генерация изображений по текстовому prompt с интерактивным Playground.
Загрузка изображений вместе с инструкцией для получения отредактированного результата с интерактивным Playground.
## Поручите интеграцию ИИ-агенту
Если вы ведете разработку с помощью Codex, Claude Code или Cursor, скопируйте приведенный ниже prompt в него. Сначала он получит текстовую версию этой страницы (добавьте `.md` к любому URL документации), а затем напишет код для вашего стека. Самые распространенные подводные камни — таймауты, безопасный парсинг `parts`, сжатие при загрузке и параметры разрешения — уже четко сформулированы в требованиях.
Интегрируйте (или отладьте) генерацию изображений по тексту + редактирование изображений Nano Banana 2.1 (`gemini-nano-banana-2.1`) в этом проекте.
Перед написанием кода ознакомьтесь с документацией: загрузите [https://docs.apiyi.com/en/api-capabilities/gemini-nano-banana-2.1/overview.md](https://docs.apiyi.com/en/api-capabilities/gemini-nano-banana-2.1/overview.md) для получения текстовой версии этой страницы. Для подробных сведений о параметрах также добавьте `.md` к страницам генерации изображений по тексту и редактирования изображений.
Требования:
1. Таймауты: используйте нативный формат Gemini `POST https://api.apiyi.com/v1beta/models/gemini-nano-banana-2.1:generateContent` и установите таймаут клиента на 360 секунд. Вызовы генерации изображений выполняются синхронно без идентификатора задачи: если клиент отключится, результат будет потерян, но за запрос все равно будет произведена тарификация. Увеличьте лимиты и на каждом промежуточном уровне (обратный прокси, шлюз, лимит выполнения serverless) — любой уровень с лимитом меньше времени генерации прервет запрос. Если вы используете Node, обратите внимание, что в undici есть три отдельных таймаута, и SDK `timeout` их не покрывает.
2. Парсинг ответа (**здесь проще всего ошибиться**): изображение передается в виде base64 в `inlineData.data` внутри `candidates[0].content.parts[]`. Однако `parts` — это **неоднородный массив, длина и порядок элементов в котором не гарантируются**: текстовая часть может идти первой, из-за чего изображение окажется по индексу 1 вместо 0. Поэтому **никогда не задавайте жестко `parts[0]` или `parts[1]`**. Вместо этого выполните итерацию по `parts`, соберите все части, содержащие `inlineData`, и возьмите **последнюю** (сложные задачи могут возвращать несколько черновиков; последний из них является финальным). Считывайте `mimeType` из ответа вместо жесткого кодирования `image/png`. Отобразите изображение и предоставьте возможность сохранить его на диск.
3. Сжатие при загрузке: для редактирования помещайте референсные изображения в виде base64 в `inlineData`. Сжимайте перед загрузкой: только файлы более 1.5MB, уменьшайте длинную сторону до 2048px (никогда не увеличивайте масштаб), пережимайте с качеством 0.9 в исходном формате и сохраняйте суммарный размер менее 6MB для запросов с несколькими изображениями. Base64 добавляет примерно треть к размеру, поэтому размер каждого изображения должен быть менее 5MB. Если сжатие одного изображения завершилось сбоем, используйте оригинал вместо сбоя всего запроса. Также: **одна часть может содержать либо `text`, либо `inlineData`, но никогда оба сразу** — корректная структура: 1 текстовая часть + N частей с изображениями.
4. Параметры разрешения: **всегда передавайте** `generationConfig.imageConfig.imageSize` (`1K` / `2K` / `4K`, по умолчанию `1K`; **эта модель не поддерживает `512` и возвращает 400, если его передать**) и `aspectRatio` (на этой странице перечислено 14 допустимых соотношений сторон). Без `aspectRatio` модель выбирает соотношение сторон на основе контента, поэтому итоговые пропорции непредсказуемы. При тарификации на основе token **разрешение напрямую определяет цену**. Предоставьте возможность выбора разрешения и соотношения сторон через выпадающие списки в интерфейсе.
5. Обработка ошибок: когда модерация контента блокирует запрос, HTTP-код остается 200, но `candidates[0].content.parts` пуст. Сначала проверьте `candidatesTokenCount == 0`, затем убедитесь, что `finishReason` не равен `STOP`. Блокировки вроде `IMAGE_SAFETY` **не тарифицируются**, и повторная отправка того же запроса один или два раза часто завершается успешно, поэтому настройте их автоматический повтор.
6. Считывайте ключ из переменной окружения `APIYI_API_KEY` и отправляйте его как `Authorization: Bearer ...`. Никогда не прописывайте его в коде и не фиксируйте в git.
7. По завершении выполните один вызов генерации изображения по тексту и один вызов редактирования изображения и покажите мне полученные изображения и стоимость обоих вызовов.
| Требование | Каких проблем позволяет избежать |
| - | - |
| Без жестко заданного индекса `parts` | Количество и порядок `parts` не гарантируются, поэтому фиксированный индекс периодически приводит к сбоям. См. [Руководство разработчика Nano Banana](/ru/api-capabilities/nano-banana-dev-guide) |
| Брать последнюю часть с изображением | Сложные правки могут возвращать несколько черновиков; последний является итоговым |
| Никогда не отправлять `512` | В версии 2.1 исключен уровень 512; код Nano Banana 2, использующий его, завершается с ошибкой 400 |
| Всегда передавать `imageSize` и `aspectRatio` | При тарификации на основе token разрешение определяет стоимость; без указания соотношения сторон модель выбирает его сама, поэтому один и тот же prompt может вернуть изображение альбомной или книжной ориентации |
| Сжимать перед загрузкой | Base64 добавляет примерно треть к размеру. См. [Сжатие изображений и разрешение на выходе](/ru/api-capabilities/image-compression-resolution) |
| Автоповтор при `IMAGE_SAFETY` | Блокировки модерации возвращают 200 без изображения и не тарифицируются; простой повтор запроса часто успешен. См. [Обработка ошибок Gemini при работе с изображениями](/ru/api-capabilities/gemini-image-error-handling) |
## Ключевые возможности
Более высокое визуальное качество по сравнению с Nano Banana 2; устранены артефакты тайлинга предыдущей версии
Более четкий текст на изображениях с меньшим количеством опечаток — отлично подходит для постеров, маркетинговых материалов и инфографики
Персонажи и сцены сохраняют согласованность в ходе диалогового редактирования
minimal / medium / high, по умолчанию medium — на один уровень больше, чем в предыдущей версии
1K / 2K / 4K; при тарификации за запрос 4K стоит столько же, сколько 1K
Включая сверхвысокие и сверхширокие 1:4, 4:1, 1:8 и 8:1; по данным Google, широкие форматы выглядят лучше в более высоком разрешении
До 10 референсов объектов + 4 референса персонажей + 3 референса стиля
Подключите инструмент `googleSearch` для изображений, требующих актуальной информации, например карточек погоды или рыночных графиков
## Отличия от Nano Banana 2
| | **Nano Banana 2.1** | Nano Banana 2 |
| - | - | - |
| ID модели | `gemini-nano-banana-2.1` | `gemini-3.1-flash-image` |
| Статус | GA; Google рекомендует для новых проектов | GA; по-прежнему доступна |
| Качество / рендеринг текста / согласованность в многошаговых диалогах | Лучше | Хорошее |
| Разрешения | 1K / 2K / 4K | 512 / 1K / 2K / 4K |
| Выходные tokens на изображение 4K | 3780 | 2520 |
| Уровни thinking | minimal / medium / high, по умолчанию medium | minimal / high, по умолчанию minimal |
| Цена Google: вход | \$1.50 / 1M | \$0.50 / 1M |
| Цена Google: выход (изображения) | \$30 / 1M | \$60 / 1M |
| Цена Google: за изображение 4K | \$0.113 | \$0.151 |
| **APIYI за запрос** | **\$0.05** | \$0.055 |
| **APIYI по tokens** | \$0.66 вход / \$13.2 выход за 1M | \$0.18 вход / \$21.6 выход за 1M |
**Что выбрать**:
* **Новые проекты** → Nano Banana 2.1: качество выше и дешевле за запрос
* **Уже используете Nano Banana 2** → для переключения достаточно сменить имя модели; если в вашем коде используется уровень `512`, сначала измените его на `1K`
* **Нужны миниатюры 512px** → оставайтесь на Nano Banana 2 или используйте [Nano Banana 2 Lite](/ru/api-capabilities/nano-banana-lite-image/overview)
* **Требуется максимальное качество** → [Nano Banana Pro](/ru/api-capabilities/nano-banana-image/overview) (\$0.09 за запрос)
## Тарифы
**Выбор режима тарификации**: Nano Banana 2.1 поддерживает два режима тарификации, которые выбираются параметром «Billing model» при создании token:
* **Pay-as-you-go** или **Pay-as-you-go Priority** → тарификация по token
* **Pay-per-request** или **Pay-per-request Priority** → тарификация за запрос
* ⚠️ **Не выбирайте Hybrid billing**
### Тарификация за запрос
| Модель | Цена APIYI | Цена Google (4K) | По сравнению с Google |
| - | - | - | - |
| **Nano Banana 2.1** `gemini-nano-banana-2.1` | **\$0.05 за запрос** (одинаково для 1K / 2K / 4K) | \$0.113 за изображение | **около 44%** |
### Тарификация по token
| Статья расходов | Google | APIYI | По сравнению с Google |
| - | - | - | - |
| Вход | \$1.50 / 1M tokens | \$0.66 / 1M tokens | **44%** |
| Выход (изображения, текст и рассуждения по единому тарифу) | Изображения \$30 / 1M; текст и рассуждения \$7.50 / 1M | \$13.2 / 1M tokens | **44%** от тарифа на изображения |
Цены на модели синхронизированы с официальным сайтом и могут меняться вслед за ним; таблица выше приведена только для справки — официальные данные всегда указаны на вкладке **Model Pricing** в верхнем меню навигации: [Model Pricing](/en/models/index).
### Тарификация по token: реальные списания в продакшене
Nano Banana 2.1 **по умолчанию выполняет рассуждение перед генерацией** (уровень по умолчанию: medium). Помимо tokens изображений, каждое изображение генерирует примерно 400–1300 tokens рассуждений и других выходных tokens, которые тарифицируются вместе с изображением по ставке \$13.2 / 1M. Поэтому стоимость одного изображения при тарификации по token **не фиксирована — она варьируется**. В таблице ниже приведены данные реальных запросов с тарификацией по token от 2026-10-07; суммы представляют собой фактические списания в консоли (разрешение определено по количеству выходных tokens):
| Сценарий | Входные tokens | Выходные tokens | Фактическое списание |
| - | - | - | - |
| 1K генерация по тексту | 36 | 1,970 | \$0.0260 |
| 1K редактирование одного изображения | 1,137 | 2,015 | \$0.0273 |
| 1K редактирование одного изображения (больше рассуждений) | 1,132 | 2,409 | \$0.0325 |
| 2K генерация по тексту | 13 | 2,623 | \$0.0346 |
| 2K редактирование одного изображения | 1,188 | 2,957 | \$0.0398 |
| 2K объединение 14 референсных изображений | 15,735 | 2,827 | \$0.0581 |
| 4K генерация по тексту | 13 | 4,703 | \$0.0621 |
| 4K сложный prompt | 72 | 4,933 | \$0.0652 |
Распределение 60 запросов с тарификацией по token за этот день:
| Разрешение | Запросы | Мин. | Медиана | Макс. | Цена за запрос |
| - | - | - | - | - | - |
| 1K | 31 | \$0.021 | \$0.029 | \$0.033 | \$0.05 |
| 2K | 19 | \$0.033 | \$0.036 | \$0.058 | \$0.05 |
| 4K | 10 | \$0.061 | \$0.063 | \$0.067 | \$0.05 |
**Какой режим тарификации выбрать**:
* **1K / 2K → по token**: обычно \$0.02–\$0.04 за изображение, что ниже цены \$0.05 за запрос
* **4K → за запрос**: фиксированные \$0.05, тогда как тарификация по token стоит \$0.06 или больше
* **Множество референсных изображений в одном запросе** (например, 10+): входные tokens повышают стоимость по token почти до \$0.05 или выше, поэтому для них также используйте тарификацию за запрос
С учётом нашего [бонуса за пополнение](/ru/faq/recharge-promotions) ваши реальные расходы будут ещё ниже.
**Почему расчёт только по tokens изображений занижает стоимость**: `thoughtsTokenCount` в `usageMetadata` не входит в `candidatesTokenCount`, но учитывается как выходные tokens в ваших логах APIYI и подлежит оплате. Оценка исходя из 1120 / 1680 / 3780 tokens занижает стоимость на 20%–40%. Сверяйте данные со списаниями в логах консоли.
## Параметры, влияющие на ваши расходы
| Параметр | Влияние на стоимость запроса | Примечания |
| - | - | - |
| `imageConfig.imageSize` | 1K \~\$0.026 → 4K \~\$0.062 (на основе tokens) | Главный фактор; не влияет на тарификацию за запрос |
| `thinkingConfig.thinkingLevel` | `high` использует примерно на 30% больше thinking tokens, около +6% для изображения 4K | Незначительное влияние; включайте при необходимости |
| `tools: [{"googleSearch": {}}]` | \$0.014 за поисковый запрос; в наших тестах выполнялось 2 запроса на изображение | Заметно увеличивает стоимость запроса |
### thinkingLevel: по умолчанию — medium, а high стоит лишь немного дороже
| Настройка | Thinking tokens (медиана) | Стоимость изображения 4K (на основе tokens) |
| - | - | - |
| Не задано (по умолчанию medium) | \~690 | \~\$0.062 |
| `high` | \~940 | \~\$0.066 |
В отличие от Nano Banana 2 (по умолчанию minimal, где `high` стоит на 54% дороже), версия 2.1 уже рассуждает по умолчанию, а `high` просто рассуждает немного дольше. Смело включайте этот параметр, когда требуется точное расположение текста на изображении или выверенные пропорции диаграмм.
### Google Search grounding: тарифицируется за поисковый запрос
Для изображений, требующих актуальной информации (карточки погоды, графики рынков, плакаты недавних событий), подключите инструмент `googleSearch`:
```json theme={null}
{
"contents": [{ "parts": [{ "text": "A weather card poster for Tokyo today" }] }],
"tools": [{ "googleSearch": {} }]
}
```
В наших тестах grounding срабатывал в 3 случаях из 3, и модель самостоятельно выполняла по 2 поисковых запроса на запрос. Каждый запрос стоит \$0.014 (\$14 за 1 000). **Модель сама решает, сколько запросов выполнить, и ограничить это заранее нельзя**, поэтому закладывайте в бюджет 2–3 запроса на каждый запрос.
**Плата за поиск взимается и при тарификации за запрос**: \$0.05 за запрос покрывают только изображение; при подключении `googleSearch` каждый поисковый запрос оплачивается дополнительно.
## Группы
Nano Banana 2.1 доступна в двух группах на APIYI; переключаться между ними можно в настройках вашего token:
| Группа | Коэффициент | Сценарий использования |
| - | - | - |
| `Default` | 1.0x | Стандартный канал по указанным ценам; рекомендуется по умолчанию |
| `NB-Enterprise` | 1.4x | Резервный канал на случай высокой нагрузки или таймаутов в группе по умолчанию; приоритет стабильности |
**Рекомендуемый режим тарификации token**: выберите `Pay-as-you-go Priority` — он поддерживает тарификацию по tokens для Nano Banana 2 / 2.1 и тарификацию за запрос для Nano Banana Pro, поэтому **один token покрывает всю линейку**. Укажите `Default` в качестве основной группы, а `NB-Enterprise` — в качестве резервной; если основная группа вернет 429, запросы автоматически переключатся на резервную и генерация продолжится.
## Разрешения и соотношения сторон
### Выходное разрешение
| Разрешение | Описание | Сценарий использования |
| - | - | - |
| 1K | По умолчанию | Социальные сети, веб |
| 2K | HD | HD-дисплеи, печать |
| 4K | Ultra HD | Профессиональный дизайн, коммерческие плакаты |
**`512` не поддерживается**: `"imageSize": "512"` возвращает 400 `Image size 512 is not supported for this model` (тарификация не производится). Измените это значение при переходе с Nano Banana 2.
### Поддерживаемые соотношения сторон (14)
`1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
**Если вы опустите `aspectRatio`, модель выберет соотношение сторон на основе содержимого**: в наших тестах промпты с описанием сцен в основном давали 16:9, а промпты для плакатов — 2:3 или 3:4. Передавайте его явно, если вам требуется фиксированное соотношение сторон.
### Фактические размеры на выходе (в пикселях)
| Соотношение | 1K | 2K | 4K |
| - | - | - | - |
| **16:9** | 1376×768 | 2752×1536 | 5504×3072 |
| **2:3** | 848×1264 | — | 3392×5056 |
| **3:4** | 896×1200 | — | — |
| **8:1** | 2928×352 | — | — |
Измерения проведены 2026-10-07; «—» означает, что замеры еще не проводились. Обратите внимание, что соотношение 8:1 при 1K составляет 2928×352, что отличается от 3072×384 в Nano Banana 2, поэтому **не используйте таблицу размеров Nano Banana 2** для фронтенд-верстки.
## Часто задаваемые вопросы
Нет. 2.1 — это отдельный ID модели, `gemini-nano-banana-2.1`, с более высоким качеством, улучшенным рендерингом текста и согласованностью в многоэтапных диалогах, а также с другой структурой тарификации (более дорогой ввод, более дешевый вывод изображений, больше tokens на изображение 4K). Обе модели доступны на APIYI и не влияют друг на друга.
1. Измените название модели с `gemini-3.1-flash-image` (или `-preview`) на `gemini-nano-banana-2.1`
2. Если вы используете `"imageSize": "512"`, измените его на `1K`
3. Если вы рассчитываете стоимость по tokens, сверьте ее с приведенной выше таблицей «Фактическая стоимость одного изображения»
Формат запроса, структура ответа, а также редактирование нескольких изображений и многоэтапное редактирование остаются прежними.
По состоянию на 7 октября 2026 года Google не объявляла дату отключения `gemini-3.1-flash-image`; версия 2.1 указана лишь как рекомендуемая замена. Nano Banana 2 на APIYI остается доступной по той же цене. Если что-то изменится, мы уведомим вас заранее.
Поскольку версия 2.1 выполняет рассуждение по умолчанию, каждое изображение добавляет примерно 400–1300 tokens рассуждения и других выходных tokens, которые тарифицируются по тарифу на вывод вместе с изображением. Вы можете увидеть их в `thoughtsTokenCount`. Если вы в основном генерируете 4K, тарификация за запрос (\$0.05) будет более выгодной.
**Лимита на параллельные запросы нет** — отправляйте параллельные запросы свободно; они не встают в очередь и не блокируют друг друга. Важен параметр `timeout`: запросы 4K или запросы в часы пик могут занимать некоторое время (в наших тестах большинство запросов 4K длились 30–50 секунд, некоторые — более 2 минут), поэтому **установите таймаут клиента на 360 секунд**. Если вы иногда сталкиваетесь с ошибками 429, добавьте `NB-Enterprise` в качестве резервной группы для вашего token.
Каждое выходное изображение содержит невидимый водяной знак SynthID (метка Google для контента, созданного ИИ). Он незаметен и никак не влияет на использование.
## Связанная документация
* [Генерация и редактирование изображений Nano Banana 2](/ru/api-capabilities/nano-banana-2-image/overview) — предыдущая версия, поддерживает 512px
* [Генерация и редактирование изображений Nano Banana Pro](/ru/api-capabilities/nano-banana-image/overview) — наивысшее качество
* [Руководство разработчика Nano Banana](/ru/api-capabilities/nano-banana-dev-guide) — управление размером, требования к входным изображениям, URL изображений
* [Тарифы Nano Banana](/ru/api-capabilities/nano-banana-pricing)
* [Обработка ошибок изображений Gemini](/ru/api-capabilities/gemini-image-error-handling)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.