Многие разработчики после подключения API Nano Banana 2 (а именно gemini-3.1-flash-image-preview) сталкиваются с обескураживающим явлением: один и тот же промпт в веб-версии gemini.google.com выдает изысканные и детализированные изображения, тогда как при вызове через чистый API результат выглядит посредственно или даже заметно хуже.
Эта разница в качестве между API Nano Banana 2 и веб-версией — не баг самого API и не проблема сервиса-прокси, а системное различие, заложенное в архитектуру продуктов Google. В этой статье мы разберем 3 фундаментальные причины этого разрыва, опираясь на технические принципы, и предложим 6 стратегий промпт-инжиниринга, которые можно внедрить прямо сейчас, чтобы добиться через API качества, сопоставимого с веб-версией или даже превосходящего её.
1. Почему Nano Banana 2 API и веб-версия дают такие разные результаты
Чтобы понять эту проблему, нужно осознать принципиальную разницу в архитектуре двух путей доступа к Nano Banana 2, предоставляемых Google.
1.1 Nano Banana 2 API — это прозрачный и чистый канал
Когда вы вызываете модель gemini-3.1-flash-image-preview через API, цепочка запроса выглядит так:
Ваша программа → API-эндпоинт → Вывод модели → Возврат изображения
Единственное, что делает API-эндпоинт с промптом — это пересылает его "как есть". Что вы написали, то модель и получила. Такая прозрачность — суть API как инфраструктуры: предсказуемость, воспроизводимость и возможность инженерной интеграции.
Сервисы-прокси (например, APIYI apiyi.com) при вызове официального API также осуществляют полностью прозрачную пересылку, выполняя лишь адаптацию протокола и учет биллинга; они не меняют ваш промпт. Поэтому результат, который вы видите при вызове через прокси, идентичен результату при прямом подключении к официальному API.
1.2 Веб-версия gemini.google.com — это комплексный агент
А вот продукт gemini.google.com, несмотря на кажущуюся простоту "генерации изображений", на самом деле представляет собой многоуровневый конвейер агентов. Когда вы вводите в поле ввода "сгенерируй ночной вид киберпанк-города", реальный путь запроса выглядит примерно так:
Ваш ввод
→ Интерфейс (UI)
→ Переписывание промпта (Prompt Rewriter на базе LLM)
→ Дополнение профессиональными описаниями композиции/света/объектива
→ Возможное обращение к Google Search / Image Search для визуальных референсов
→ Передача итогового расширенного промпта модели
→ Возврат изображения
Google официально упоминает наличие этого Prompt Rewriter в документации Vertex AI — это "инструмент для переписывания промптов на базе LLM", который повышает качество выходных изображений, добавляя детали и описательные характеристики к базовому запросу. Потребительский продукт gemini.google.com имеет встроенные возможности аналогичного уровня.
1.3 Суть разницы — в обработке промпта, а не в возможностях модели
Здесь важно прояснить ключевой факт: API и веб-версия используют одну и ту же базовую модель. Разница не в самой модели, а в том, кто написал текст, который подается на вход.
| Способ вызова | Кто обрабатывает промпт | Типичная длина промпта | Качество вывода |
|---|---|---|---|
| Веб-версия gemini.google.com | Автоматическое расширение встроенным агентом Google | 200-500 слов | Изысканно, профессионально, детально |
| Официальный API Nano Banana 2 | Разработчик пишет сам | Ввод пользователя (обычно 10-30 слов) | Зависит от навыков разработчика |
| Вызов через APIYI apiyi.com | Разработчик пишет сам (прозрачная пересылка) | Ввод пользователя | Идентично официальному API |
| Вызов API после ручной предобработки | Разработчик + LLM-препроцессинг | 200-500 слов | Может приближаться к веб-версии или превосходить её |
🎯 Основной вывод: Разница в качестве между API Nano Banana 2 и веб-версией на 95% обусловлена обработкой промпта, а не интерфейсом, прокси-сервером или различиями в весах модели. Это означает, что как только вы добавите этап промпт-инжиниринга, вы сможете заставить API выдавать результат, не уступающий веб-версии.
二、Nano Banana 2 API 的技术规格与能力边界
在讨论解决方案前，先明确 API 本身的能力边界——这样你才能判断哪些是“提示词能救的”，哪些是“需要调整请求参数的”。
2.1 Nano Banana 2 API 的关键参数
| 参数 | 取值范围 | 默认值(网页版) | 默认值(API) | 说明 |
|---|---|---|---|---|
| 分辨率 | 512px / 1K / 2K / 4K | 2K | 1K | 网页版默认更高 |
| 长宽比 | 1:1, 16:9, 9:16, 2:3, 3:2, 4:3, 3:4, 4:5, 5:4, 21:9, 4:1, 1:4, 8:1, 1:8 | 1:1 | 1:1 | 一致 |
| 参考图数量 | 最多 14 张 | — | — | Flash 版: 10 物体+4 角色 |
| 输入 token | 最多 131,072 | — | — | Flash 版上限 |
| 提示词长度 | 建议 50-500 词 | Agent 自动补齐 | 用户原样 | 差距核心 |
| 是否支持 Grounding | 支持 Google Search | 部分开启 | 需显式调用 | 搜索增强能力 |
这里最容易被忽视的一点是：API 默认分辨率是 1K，而网页版默认是 2K。仅这一项配置差异，就会让裸调用 API 的输出在肉眼观感上显著弱于网页版，哪怕提示词完全相同。
2.2 Nano Banana 2 API 调用的最小示例
以下是标准的 curl 调用方式，展示如何显式指定 2K 分辨率，避免默认 1K 带来的观感落差：
curl -X POST "https://api.apiyi.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"messages": [
{
"role": "user",
"content": "生成一张赛博朋克风格的城市夜景,2K 分辨率,16:9 构图"
}
]
}'
💡 配置建议: 通过 APIYI apiyi.com 调用时，
base_url使用https://api.apiyi.com/v1，模型 ID 与官方保持一致，无需任何代码改造。服务-прокси API 的透明性保证了 你在官方 API 上看到的表现，在 APIYI 上看到的也是完全一致的表现。
2.3 Nano Banana 2 API 支持的两个模型版本
| 模型 ID | 定位 | 典型用途 | 响应速度 | 成本 |
|---|---|---|---|---|
gemini-3-pro-image-preview |
Nano Banana Pro,高保真旗舰 | 营销物料、信息图、文字渲染 | 中等 | 较高 |
gemini-3.1-flash-image-preview |
Nano Banana 2,速度优先 | 批量生成、社交素材 | 快 | 较低 |
选择建议：Pro 版适合对文字渲染和画面层次要求高的场景，Flash 版适合高并发、低延迟的批量生产。无论哪个版本，提示词工程的收益都是巨大的。
三、Nano Banana 2 API 提示词工程的 6 个核心策略
明确了差距来源后，下面进入可落地的解决方案。这 6 个策略来自 Google DeepMind 官方的 Nano Banana 提示词指南，以及大量 API 用户的实战经验沉淀。
3.1 使用五元素提示词公式
Google 官方推荐的 文本到图像公式 是：
[Subject 主体] + [Action 动作] + [Location 场景] + [Composition 构图] + [Style 风格]
这不是生硬的拼接，而是确保你的提示词覆盖了视觉生成所需的所有维度。对比示例：
❌ 典型的弱提示词：
一个时尚模特在红色背景前拍照
✅ 套用五元素公式的强提示词：
[Subject] 一位约 28 岁的时尚模特,身着剪裁利罗的棕色西装连衣裙,搭配流线型及膝靴和结构化手提包
[Action] 以自信而挺拔的姿态站立,身体微微侧转,眼神凝视镜头
[Location] 深樱桃红色纯色影棚背景
[Composition] 中景,主体居中构图,稍留顶部空间
[Style] 时尚杂志大片,中画幅胶片质感,明显颗粒,高饱和度
两个提示词的字数差 5 倍，但生成质量差距远不止 5 倍。这正是网页版 Agent 在“幕后”为普通用户做的事。
3.2 Nano Banana 2 API 要求叙述性描述而非关键词列表
这是 Google 官方反复强调的一条原则：“Describe the scene, don't just list keywords.”
❌ 关键词堆砌(模型容易失焦)：
时尚, 模特, 工作室, 红色背景, 专业摄影, 4K, 高质量
✅ 连贯叙述(模型更容易理解语义)：
一位时尚模特在专业工作室的深红色背景前拍摄大片,镜头捕捉她挺拔站立的瞬间,
采用中画幅相机的胶片质感,画面呈现时尚杂志特有的高饱和色彩。
Nano Banana 2 是一个 叙事驱动型 的模型，它更擅长理解一个“场景描述”而不是一串“标签”。这个特性与传统的 Stable Diffusion 系提示词习惯完全不同，从 SD 迁移过来的开发者尤其需要改变思维方式。
3.3 Nano Banana 2 API 必须补充的视觉元数据
网页版 Agent 会自动为你的简单请求补充“视觉元数据”——这些词汇是将模型输出从“普通”推向“专业”的关键。
| 元数据类别 | 推荐词汇举例 | 作用 |
|---|---|---|
| 光照设计 | 三点布光、Chiaroscuro 明暗对照、金色时刻逆光、冷蓝色霓虹辉光 | 决定画面戏剧性 |
| 相机与镜头 | 85mm 人像镜头、f/1.8 浅景深、GoPro 广角、微距镜头 | 决定视觉语言 |
| 色调与胶片 | 1980s 彩色胶片、电影级冷蓝色调、柯达 Portra 400、RAW 高动态范围 | 决定色彩氛围 |
| 材质与纹理 | 深蓝色粗花呢、哑光陶瓷表面、银色刻纹盔甲、做旧皮革 | 决定细节质感 |
| 构图术语 | 低角度、鸟瞰、三分法、浅景深、中心对称 | 决定画面结构 |
💡 实战建议: 在写提示词时，强制要求自己至少从光照、相机、色调、材质、构图中选 3 类补充具体描述。这是让 Nano Banana 2 API 输出从“业余”变“专业”的捷径。完整的提示词参考库可以在 APIYI apiyi.com 的开发者文档中找到。
3.4 文字渲染类 Nano Banana 2 API 调用必须用引号包裹
Nano Banana 2（尤其是 Pro 版）最突出的能力之一是 高保真文字渲染——可以准确生成 Logo、海报、信息图中的文字。但要触发这个能力，你必须：
- 将目标文字用引号包裹 (英文双引号
") - 指定字体特征 (粗体/衬线/手写等)
- 指定颜色和大小 (可选，但建议)
对比示例：
❌ 模糊写法(文字容易错乱)：
生成一张生日贺卡,上面写 Happy Birthday
✅ 标准写法(文字渲染准确)：
生成一张生日贺卡,卡片中央用粗体、白色、无衬线字体渲染 "Happy Birthday",
字号约占画面宽度的 60%,背景为浅粉色调的梦幻气球场景。
这是 Nano Banana 2 API 相比其他图像模型的一项 硬核差异化能力，许多开发者在做营销物料时还没意识到可以这样用。
3.5 编辑类任务要明确“改什么”与“保留什么”
图像编辑(i2i)的提示词思维与文生图(t2i)完全不同——它不是描述整个画面，而是告诉模型哪些要变、哪些要保持。
❌ 编辑类常见错误写法：
把这个人变成穿红色外套
(模型可能同时改变背景、姿态、光线等未提及的要素)
✅ 明确范围的编辑写法：
将图中人物的外套颜色从蓝色更改为鲜艳的番茄红色,
保持人物的面部特征、发型、姿态、背景和光线完全不变。
明确保留原图的所有非外套元素。
这种“变更 + 保留”的双重声明，可以显著降低编辑偏差。Nano Banana 2 API 的多轮编辑场景下，配合 Thought Signatures 机制能实现跨轮次的一致性。
3.6 用 LLM 做提示词预处理(复刻网页版 Agent)
这是最治本的策略：既然网页版通过 Agent 自动改写提示词，那我们在调用 API 前，也用一个 LLM 先做一次提示词扩写。
具体做法是在你的应用逻辑里加一层“前置 LLM”：
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1"
)
def expand_prompt(user_input: str) -> str:
"""用 LLM 将用户的简单提示词扩写为专业级提示词"""
response = client.chat.completions.create(
model="gemini-3-pro",
messages=[
{
"role": "system",
"content": (
"你是资深视觉艺术总监,负责将用户简短描述扩写为图像模型的详细提示词。"
"必须包含: 主体细节、动作、场景、构图、光照、相机参数、色调、材质。"
"使用连贯叙述,不要关键词列表,总长度 150-300 字。"
)
},
{"role": "user", "content": user_input}
]
)
return response.choices[0].message.content
def generate_image(user_input: str):
expanded = expand_prompt(user_input)
image_response = client.chat.completions.create(
model="gemini-3-pro-image-preview",
messages=[{"role": "user", "content": expanded}]
)
return image_response
generate_image("赛博朋克城市夜景")
这段代码的核心逻辑就是 手动实现了一个 Prompt Rewriter Agent——用 Gemini 3 Pro(或 Claude、GPT-4)先把用户的简短输入扩写，再交给图像模型。效果上基本可以达到 gemini.google.com 网页版的水准。
🎯 落地建议: 如果你在做 C 端图片生成产品，强烈推荐采用“双模型串联”架构：一个文本 LLM 负责提示词扩写，一个图像模型负责最终生成。两个调用都可以通过 APIYI apiyi.com 统一计费，简化接入成本。该平台支持 Gemini、Claude、GPT 等多个主流模型的统一接口，便于架构演进。
IV. Практика использования шаблонов промптов для API Nano Banana 2
Ниже представлены 4 проверенных на практике шаблона промптов, которые можно использовать как есть или взять за основу для своих задач.
4.1 Шаблон промпта для товарной фотографии (e-commerce)
[Subject] [Тип продукта], [описание материала], [цвет и текстура], [ключевые особенности дизайна]
[Action] Продукт парит в центре кадра, слегка наклонен для демонстрации лучшего ракурса
[Location] [Цвет фона или сцена], чистый или минималистичный фон
[Composition] Квадрат 1:1, продукт занимает 60% кадра, сверху оставлено место для текста
[Style] Профессиональная предметная съемка, мягкий верхний и боковой свет, матовая текстура, высокое разрешение
[Text] В верхней части кадра отрендерить "[Слоган продукта]" с использованием [описание шрифта]
4.2 Шаблон промпта для рекламного постера
Создай рекламный постер на тему [Праздник/Событие] для бренда [Название бренда],
В центре кадра [основной визуальный элемент], используй язык дизайна [стиль, например: плоский/скевоморфизм/ретро],
Основная цветовая гамма [HEX-код], дополнительный цвет [HEX-код],
В нижней части постера отрендерить "[Слоган события]" жирным шрифтом без засечек,
Композиция с достаточным количеством свободного пространства, четкая визуальная иерархия, подходит для [сценарий размещения].
4.3 Шаблон промпта для обеспечения согласованности лиц
Используется для поддержания единообразия персонажа на нескольких изображениях (при использовании до 14 эталонных изображений):
[Описание персонажа на основе эталонного изображения]
Этот персонаж появляется в [новая сцена],
[Описание нового действия], [новое выражение лица],
Одет в [описание одежды], как на эталонном изображении,
Сохраняй черты лица, прическу, пропорции тела в точном соответствии с эталонным изображением.
Стиль изображения: [сохранять единообразие освещения и цветовой гаммы]
4.4 Шаблон для инфографики и визуализации знаний
Создай инфографику на тему [Тема],
Область заголовка: в верхней части отрендерить "[Текст заголовка]" жирным белым шрифтом,
Основная структура: [описание визуальной иерархии, например: сравнение в 3 колонки/таймлайн/пирамидальная структура],
Каждый модуль содержит [тип иконки] + заголовок + краткое пояснение,
Цветовая схема: темно-синий фон #0f172a, основной текст белый, акцентный цвет [HEX-код],
Общий стиль: современный технологичный, плоские иконки, высокая контрастность, подходит для презентаций.
💡 Совет по использованию: Эти шаблоны постоянно обновляются в сообществе разработчиков APIYI (apiyi.com) и охватывают такие категории, как электронная коммерция, социальные сети, маркетинг, образование и другие.
V. Распространенные ошибки и отладка при вызове API Nano Banana 2
Помимо самих промптов, существуют типичные технические ошибки, которые создают ложное впечатление, что «API работает хуже, чем веб-версия».
5.1 Ловушки параметров по умолчанию
| Ошибка | Симптомы | Решение |
|---|---|---|
| Не задано разрешение | Размытая картинка 1K | Явно установите 2K или 4K |
| Не задано соотношение сторон | Стандартное 1:1 не подходит под задачу | Укажите 16:9, 9:16 и т.д. |
| Grounding отключен | Неточности в изображениях, требующих реальных данных | Явно включите для сценариев с поиском |
| Слишком высокая температура | Высокая случайность результата | Снизьте temperature для задач, требующих детерминизма |
| Игнорирование Thinking | Модель Pro не использует рассуждения | Явно включите thinking_level |
5.2 Проверка согласованности сервиса-прокси и официального API
Некоторые разработчики подозревают, что «сервис-прокси что-то подкрутил, из-за чего упало качество». Эти опасения излишни, но их можно проверить двумя способами:
- Сравнение логов запросов: Отправьте один и тот же промпт через официальный API и через APIYI (apiyi.com), сравните хеши вывода или просто оцените визуально — вы увидите, что распределение результатов идентично.
- Проверка заявлений о прозрачности: Качественный сервис-прокси занимается только пересылкой протоколов и биллингом, он не меняет промпт на лету. APIYI (apiyi.com) гарантирует прозрачное прямое соединение, обеспечивая работу интерфейса в точности как у официального провайдера.
Поэтому, если вы обнаружили, что качество через API (неважно, официальный или прокси) хуже, чем в веб-версии, истинная причина кроется в промпт-инжиниринге, а не в промежуточном звене.
5.3 Разница в качестве из-за выбора версии модели
Это крайне распространенная, но часто упускаемая из виду ошибка:
- Результат
gemini-2.5-flash-image(старый Nano Banana) определенно будет хуже, чемgemini-3.1-flash-image-preview(Nano Banana 2). - Использование
gemini-3.1-flash-image-preview(приоритет скорости) для создания маркетинговых материалов даст результат хуже, чемgemini-3-pro-image-preview(приоритет качества).
Прежде чем жаловаться на «плохое качество API», убедитесь, что вы вызываете самую новую и подходящую модель.
VI. Продвинутые техники промпт-инжиниринга для Nano Banana 2 API
Освоив предыдущие 6 стратегий, вы можете использовать продвинутые методы, которые помогут добиться результатов, значительно превосходящих обычные вызовы моделей.
6.1 Регулировка уровня мышления (Thinking Level)
Nano Banana Pro поддерживает явную настройку глубины «мышления». Для задач со сложной композицией, множеством элементов или мелким текстом включение более высокого уровня мышления значительно повышает вероятность успеха. Единственный минус — увеличение задержки.
6.2 Grounding с поиском Google
Для задач генерации, требующих «соответствия реальности» — например, при работе с реальными достопримечательностями, недавними новостными событиями или логотипами брендов — включение функции Grounding позволяет модели сначала выполнить поиск, а затем генерацию. Это помогает избежать фактических ошибок и является уникальным преимуществом Nano Banana 2 API по сравнению с другими моделями генерации изображений.
6.3 Сохранение контекста при многоходовом редактировании
Nano Banana 2 API поддерживает многоэтапное редактирование изображений. В отличие от генерации с нуля каждый раз, многоходовое редактирование позволяет сохранять Thought Signatures (сигнатуры мышления), благодаря чему персонажи, сцены и стили естественным образом переносятся между изображениями.
VII. FAQ: Часто задаваемые вопросы по Nano Banana 2 API
В1: Есть ли разница в результатах при использовании Nano Banana 2 API через APIYI (apiyi.com) и через официальный API Google?
Разницы нет. Суть сервиса-прокси API заключается в прозрачной передаче протоколов. APIYI (apiyi.com) занимается только аутентификацией, биллингом и адаптацией протоколов, не изменяя промпт или содержимое ответа. Результаты, которые вы видите в официальном API, будут абсолютно идентичны тем, что вы получите через APIYI. Рекомендуем использовать apiyi.com для удобства единого биллинга по нескольким моделям и стабильного доступа из РФ.
В2: Почему после оптимизации промпта по вашим советам результат все равно хуже, чем в веб-версии?
Возможные причины: (1) разрешение все еще стоит по умолчанию 1K, попробуйте установить 2K или 4K; (2) возможности LLM, используемой для расширения промпта, недостаточно, рекомендуем использовать Gemini 3 Pro или Claude 4; (3) не включен режим Thinking (в версии Pro); (4) недостаточно эталонных изображений — Nano Banana 2 поддерживает до 14 штук, их грамотное использование значительно повышает согласованность лиц и объектов.
В3: Что выбрать: Nano Banana 2 (Flash) или Nano Banana Pro?
Простое правило: если нужны качественный рендеринг текста, инфографика или постеры — выбирайте Pro; если важны высокая параллельность, пакетная генерация и низкая стоимость — выбирайте Flash. Обе версии доступны в APIYI (apiyi.com), для переключения достаточно изменить ID модели.
В4: Какую модель лучше всего использовать для предварительной обработки промптов?
Рекомендуем Gemini 3 Pro или Claude 4 Sonnet. Семейство Gemini лучше всего понимает специфику моделей генерации изображений (все-таки один разработчик), а Claude обладает уникальными преимуществами в расширении описаний в повествовательном стиле. Обе модели можно подключить через APIYI (apiyi.com).
В5: Есть ли готовые инструменты для оптимизации промптов?
На данный момент официальных отдельных инструментов нет, но вы можете создать свой сервис Prompt Rewriter, используя код из раздела 3.6 этой статьи. Также в сообществе есть несколько open-source проектов типа image-prompt-enhancer, на которые можно ориентироваться.
В6: Сильно ли вырастет стоимость вызова API из-за увеличения длины промпта?
Тарификация Nano Banana 2 в основном зависит от количества сгенерированных изображений, а доля токенов промпта в стоимости невелика. Даже если вы расширите промпт с 20 до 300 слов, стоимость одного вызова вырастет менее чем на 5%, при этом качество генерации заметно улучшится, что дает отличный ROI (окупаемость инвестиций).
VIII. Итоги: в чем причина разрыва между Nano Banana 2 API и веб-версией и как его преодолеть
Возвращаясь к вопросу, поставленному в начале статьи: почему между API и веб-версией такая большая разница? Ответ теперь очевиден:
- Первопричина: Веб-версия gemini.google.com — это комплексный агент со встроенным механизмом переписывания промптов (Prompt Rewriter), который автоматически расширяет пользовательский ввод. API же работает напрямую: что отправили, то и получили.
- Суть: Дело не в разнице между моделями и не в качестве сервиса-прокси API, а в отсутствии этапа предварительной обработки промпта.
- Решение: Использование 6 стратегий — формулы пяти элементов, описательного повествования, дополнения визуальных метаданных, выделения текста кавычками, определения области редактирования и предварительного переписывания через LLM — позволит результатам API догнать и даже превзойти веб-версию.
- Оптимальная архитектура: Реализация связки из двух моделей на уровне приложения («LLM для расширения текста + модель для генерации изображений») полностью решает проблему разрыва в качестве.
Для команд, которые уже используют Nano Banana 2 API в продакшене, повышение уровня промпт-инжиниринга до статуса качества кода — это наиболее эффективный способ оптимизации с точки зрения ROI. Мы рекомендуем использовать APIYI (apiyi.com) для унифицированного доступа к текстовым и графическим моделям. Это не только упрощает интеграцию нескольких моделей, но и позволяет быстро переключаться между ними и сравнивать их эффективность.
Об авторе: Техническая команда APIYI специализируется на предоставлении разработчикам стабильного, прозрачного и всеобъемлющего доступа к API больших языковых моделей. Посетите официальный сайт APIYI (apiyi.com), чтобы узнать больше о решениях для доступа к таким популярным моделям, как Nano Banana 2, Gemini 3 Pro, Claude 4 и другим.
