> ## 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 > Универсальное руководство по выбору модели, тарификации, эндпоинтам, форматам разработки и FAQ для серии Nano Banana (Pro / 2 / 2 Lite / Gen 1), помогающее разработчикам начать работу с Gemini API генерации изображений. ## Model Cards | Model | Официальный ID модели | Тарификация | Примечания | | ----------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | **Nano Banana Pro** | `gemini-3-pro-image-preview` | Фиксированная оплата за запрос **\$0.09/req** (примерно ¥0.63; примерно ¥0.55 после промоакций пополнения) | Высочайшее качество | | **Nano Banana 2** | `gemini-3.1-flash-image-preview` | За запрос **\$0.055/req** (рекомендуется для вывода 4K); или динамическая тарификация на основе token, 2K примерно **\$0.04** | Лучшее соотношение цены и качества | | **Nano Banana 2 Lite** | `gemini-3.1-flash-lite-image` | Фиксированная оплата за запрос **\$0.025/req**; или тарификация на основе token примерно **\$0.018/req** (40% от официальной цены) | Самый быстрый и дешевый, только 1K | | **Nano Banana** (Gen 1) | `gemini-2.5-flash-image` | Фиксированная оплата за запрос **\$0.02/req** | Самый дешевый | Для полного сравнения цен, тарификации за запрос и на основе token, а также рекомендаций по выбору token см. [Тарификация серии Nano Banana](/ru/api-capabilities/nano-banana-pricing). ### Управление размером * **Сохраняйте соотношение сторон исходного изображения**: просто опустите `aspectRatio`; в сценариях редактирования нескольких изображений приоритет имеет **размер последнего изображения** * **Разрешение `imageSize`**: поддерживает `1K` / `2K` / `4K` * Nano Banana (Gen 1) **поддерживает только 1K** * Nano Banana 2 **добавляет 512px** * Nano Banana 2 Lite **поддерживает только 1K** (без 2K/4K/512px) При использовании того же кода для вызова первого поколения `gemini-2.5-flash-image` вы **должны удалить параметр `imageSize`** (он не поддерживает `2K` / `4K`), иначе вызов завершится ошибкой. ## Как интегрировать ### Официальная документация * Официальная документация Google: `ai.google.dev/gemini-api/docs/image-generation` * Чтобы интегрироваться с APIYI, просто замените **URL запроса + KEY на APIYI**; все остальные параметры идентичны официальным ### Проверка официального статуса (диагностика проблем на стороне upstream) Серия Nano Banana работает поверх Google AIStudio / Gemini API. В редких случаях **размытый или неудачный вывод 2K / 4K** может быть проблемой на **стороне Google**, а не на уровне интеграции — вы можете проверить официальную страницу статуса Google (скопируйте и откройте ее сами): `aistudio.google.com/status`. Например, 19 июня 2026 года на этой странице было указано «Проблемы с Nano Banana»: у Nano Banana 2 / Pro в Gemini API и AI Studio возникали проблемы при разрешении 2K или 4K. Когда вы видите похожие симптомы, сначала сравните их с официальной страницей статуса, чтобы быстро понять, является ли это сбоем на стороне upstream. APIYI запускает серию Nano Banana через **два канала AIStudio + Vertex** для резервирования: когда у одного официального канала возникают проблемы, другой может взять на себя обслуживание, чтобы сервис оставался доступным. ### Поддержка эндпоинтов * **Рекомендуемый эндпоинт** (нативный Gemini): `https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent` * Поддерживает вызовы в **режиме, совместимом с OpenAI** (примечание: **загрузка через URL не поддерживается**, используйте Base64 вместо этого) * **Не поддерживает** `/v1/image/generations` ### Формат разработки (рекомендуется по умолчанию) * **\[Рекомендуется] Используйте нативный формат эндпоинта Google** * Изображения: **загружайте как Base64, скачивайте и повторно размещайте** * Метод вызова: **синхронные многопоточные вызовы**; асинхронные вызовы пока не поддерживаются ## Требования к входным изображениям * **Одно изображение не может превышать 7MB** (правило Google); если импорт выполняется через Google Cloud Storage, ограничение на один файл составляет 30MB * **До 14 изображений на один prompt** * **Поддерживаемые MIME types**: `image/png`, `image/jpeg`, `image/webp`, `image/heic`, `image/heif` (формат `jpg` уже поддерживается APIYI) * **Увеличение размера при Base64**: преобразование изображения в Base64 увеличивает его размер примерно на **33.3%** (изображение 7MB становится примерно 9.3MB) * **Лимит APIYI**: общий объем изображений, загружаемых в одном запросе, должен быть **менее 100MB** — все вызовы являются синхронными, а слишком большие payloads могут привести к резкому росту потребления памяти Официальная таблица технических характеристик Google Gemini 3 Pro Image: лимит для одного изображения 7MB, до 14 изображений на один prompt, поддерживаемые соотношения сторон и MIME types Расчет увеличения размера Base64: исходное изображение 7MB после кодирования с коэффициентом 4/3 становится примерно 9.33MB **Лучший способ**: применяйте **сжатие без потерь** к изображениям перед отправкой в API, чтобы избежать слишком больших разрешений, замедляющих выполнение запросов. Ссылка на официальную спецификацию Google (пожалуйста, скопируйте и откройте ее самостоятельно): `docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image` ## Ввод изображения по URL Помимо Base64, **нативный эндпоинт Gemini** также поддерживает передачу URL изображений (адреса хостов изображений / OSS) напрямую через `fileData.fileUri`, устраняя необходимость локального кодирования. **Загрузка по URL предъявляет строгие требования к хостам изображений и адресам OSS**: если адрес не находится на глобальном CDN (например, Tencent Cloud Object Storage по умолчанию использует CDN только для Китая), серверы Google с очень высокой вероятностью не смогут достичь изображения, из-за чего запрос завершится ошибкой (типичный симптом: **изображение не упоминается** в выводе). **Если возможно, для большей стабильности предпочитайте загрузку через Base64** — с точки зрения платформы это наиболее проработанный с точки зрения эксплуатации и самый надежный путь. Загрузка по URL работает только в **нативном эндпоинте Gemini**; **режим, совместимый с OpenAI, не поддерживает загрузку по URL** и требует Base64. ### Пример Curl (fileUri) ```bash theme={null} curl --location 'https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent' \ --header 'Authorization: Bearer sk-' \ --header 'Content-Type: application/json' \ --data '{ "contents": [ { "parts": [ { "fileData": { "fileUri": "https://raw.githubusercontent.com/apiyi-api/ai-api-code-samples/refs/heads/main/Vision-API-OpenAI/otter.png", "mimeType": "image/png" } }, { "text": "add five dogs" } ], "role": "user" } ], "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }}, "safetySettings": [] }' > output.json ``` ### Пример на Python (fileUri) ```python theme={null} #!/usr/bin/env python3 # -*- coding: utf-8 -*- """ Gemini 3 Pro Image - Image editing (minimal file_uri version) Purpose: only for a quick check that the endpoint works """ import requests import base64 import json from pathlib import Path from datetime import datetime # ============================================================================ # Configuration # ============================================================================ API_KEY = "sk-" API_URL = "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" # Image URL IMAGE_URL = "https://raw.githubusercontent.com/apiyi-api/ai-pics/refs/heads/main/1762260696217_dd0352c1f9604540.png" IMAGE_MIME_TYPE = "image/png" # Edit instructions EDIT_PROMPT = "Change the person's clothes to a blue jacket and hair to a purple gradient; keep pose, gaze direction, and other structural features unchanged." SYSTEM_PROMPT = "You are a professional expert in image description and generation. Your task is to produce high-quality image prompts with rich detail and a clear artistic style, or to make accurate, creative edits to existing images, based on the user's request." # Output parameters ASPECT_RATIO = "9:16" RESOLUTION = "4K" MAX_OUTPUT_TOKENS = 8000 OUTPUT_FILE = f"minimal_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png" # ============================================================================ # Core # ============================================================================ def main(): print("=" * 60) print("Testing file_uri endpoint") print("=" * 60) print(f"Image URL: {IMAGE_URL[:80]}...") print(f"Edit prompt: {EDIT_PROMPT}") print(f"Output params: {RESOLUTION}, {ASPECT_RATIO}") print("-" * 60) # Build the request body # Note: fileData, mimeType, fileUri must be in camelCase payload = { "generationConfig": { "responseModalities": ["IMAGE", "TEXT"], "imageConfig": { "imageSize": RESOLUTION, "aspectRatio": ASPECT_RATIO }, "maxOutputTokens": MAX_OUTPUT_TOKENS }, "contents": [ { "role": "model", "parts": [{"text": SYSTEM_PROMPT}] }, { "role": "user", "parts": [ { "fileData": { # camelCase: fileData (not file_data) "mimeType": IMAGE_MIME_TYPE, # camelCase: mimeType "fileUri": IMAGE_URL # camelCase: fileUri } }, {"text": EDIT_PROMPT} ] } ] } # Send the request print("\nSending request...") try: response = requests.post( API_URL, json=payload, headers={ "Content-Type": "application/json", "Authorization": f"Bearer {API_KEY}" }, timeout=300 ) print(f"Response status: {response.status_code}") if response.status_code != 200: print(f"❌ Error: {response.text}") return # Parse the response data = response.json() print("✅ Response received") # Save full response for debugging with open(OUTPUT_FILE + ".response.json", "w", encoding="utf-8") as f: json.dump(data, f, indent=2, ensure_ascii=False) print(f"📄 Response saved: {OUTPUT_FILE}.response.json") # Extract and print text parts = data["candidates"][0]["content"]["parts"] for part in parts: if "text" in part: print(f"\n💬 Text response: {part['text']}") # Save image for part in parts: if "inlineData" in part or "inline_data" in part: image_data = part.get("inlineData", part.get("inline_data", {})).get("data") if image_data: image_bytes = base64.b64decode(image_data) with open(OUTPUT_FILE, "wb") as f: f.write(image_bytes) print(f"\n✅ Image saved: {OUTPUT_FILE}") print(f"📦 File size: {len(image_bytes) / 1024:.1f} KB") print(f"🔗 File path: {Path(OUTPUT_FILE).resolve()}") return print("⚠️ No image data found in the response") except requests.Timeout: print("❌ Request timed out") except Exception as e: print(f"❌ Error: {e}") if __name__ == "__main__": main() print("\n" + "=" * 60) print("Test finished") print("=" * 60) ``` `fileData`, `mimeType` и `fileUri` должны быть в **camelCase** (а не `file_data` / `file_uri`); в противном случае параметры будут проигнорированы, и изображение не будет использовано. ## Основы тарификации (Важно) * **Длительность синхронного вызова**: Pro / 2 при 4K требуют разумного времени генерации, примерно **30–150с** * **Отключение при тайм-ауте все равно влечет списание**: например, если генерация занимает 120с, а клиент устанавливает тайм-аут 100с и отключается, с вас все равно будет взиматься плата * **429 / 503 не тарифицируются**: неудачные запросы не подлежат тарификации (мы стараемся не заставлять клиентов ждать или оставаться без изображения) * **Отказы по content-safety все равно влекут списание**: когда во входных данных клиента есть проблемы с content-safety и Google отказывается генерировать изображение, **статус-код 200 все равно тарифицируется** — см. обработку ошибок и план гарантии ниже ## Настройки таймаута (Важно) Генерация изображений 4K в целом занимает больше времени, включая такие этапы, как **загрузка изображения, обработка API и загрузка изображения Base64** (наш backend выставляет тарификацию по **времени обработки API**). При нормальных условиях 4K занимает около **50s** (без учета polling), но если клиент задаст слишком короткий timeout, он **отсоединится преждевременно** до завершения генерации и вернет ошибку: ```text theme={null} API Connection Error: HTTPSConnectionPool(host='api.apiyi.com', port=443): Read timed out. (read timeout=120) ``` Журналы вызовов: время до первого байта для генерации gemini-3-pro 4K составляет от 43 до 61 секунд Для большей надежности рекомендуем задавать timeout в зависимости от разрешения: ```python theme={null} timeout = { "1K": 300, # 5 minutes - quick preview "2K": 300, # 5 minutes - recommended "4K": 600, # 10 minutes - ultra HD } ``` ## Многораундовое разговорное редактирование (нативный формат поддерживает это; обратные модели — нет) Серия Nano Banana использует **нативный формат Gemini** и поддерживает **настоящее разговорное многораундовое редактирование**: добавляйте сгенерированное изображение каждого раунда обратно в `contents` как **`role: "model"` `inlineData`**, затем отправляйте следующую инструкцию пользователя. Модель редактирует на основе **полной истории разговора** и **накапливает изменения** (например, сначала перекрасьте диван, затем добавьте аксессуар — предыдущее изменение сохраняется). Это принципиально отличается от «обратных» моделей изображений — разберитесь с этим до интеграции: | Аспект | Nano Banana (нативный Gemini) | Обратная модель (например, `gpt-image-2-all`) | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | Эндпоинт | `/v1beta/...:generateContent` | `/v1/chat/completions` (в стиле chat) | | Механизм многораундового взаимодействия | ✅ **Настоящее разговорное**: добавляйте `role:model` изображения обратно в `contents`; модель читает историю | ❌ Нет состояния разговора: изображения в истории `assistant` **игнорируются** | | Накопление изменений между раундами | ✅ Поддерживается (красный диван → добавьте шляпу, диван остается красным) | ⚠️ Только повторная подача, одношаговое редактирование | | Как редактировать предыдущее изображение | Добавьте последнее изображение как `model` изображение в историю разговора | Передайте URL предыдущего изображения как ссылку в **новом сообщении пользователя** | Проверено: добавление предыдущего изображения как раунда с ролью `model` позволяет Nano Banana 2 (`gemini-3.1-flash-image-preview`) корректно продолжать редактирование и накапливать изменения; обратная модель читает только опорное изображение из **последнего сообщения пользователя**, поэтому сохранение истории разговора там не работает для многораундового режима. Минимальный пример (добавляйте каждый результат обратно в один и тот же `contents`): ```python theme={null} import requests, base64 API_KEY = "sk-your-api-key" URL = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} CFG = {"responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K"}} contents = [] # keep one running conversation history def turn(instruction, save_to): contents.append({"role": "user", "parts": [{"text": instruction}]}) data = requests.post(URL, headers=H, json={"contents": contents, "generationConfig": CFG}, timeout=300).json() part = next(p for p in data["candidates"][0]["content"]["parts"] if "inlineData" in p) contents.append({"role": "model", "parts": [part]}) # key: backfill the output image with open(save_to, "wb") as f: f.write(base64.b64decode(part["inlineData"]["data"])) turn("Generate an orange cat sitting on a blue sofa, simple line-art style", "step1.png") turn("Make the sofa red; keep the cat and composition unchanged", "step2.png") # edits the previous image turn("Put a small yellow hat on the cat; keep everything else the same", "step3.png") # accumulates; red sofa kept ``` Подробности (стили history-backfill и re-feed, начало многораундового редактирования с существующего изображения) см. в [API редактирования изображений · Многораундовое разговорное редактирование](/ru/api-capabilities/nano-banana-2-image/image-edit#multi-turn-conversational-editing). ## Почему ответы иногда содержат несколько изображений При вызове `gemini-3-pro-image` вы иногда можете увидеть **несколько частей изображения в одном ответе (в тестах наблюдалось 2–10)**, что соответствует периодическим записям output-token 6000+ (даже пятизначным) в ваших логах. Это не аномалия: в официальной документации Google указано, что у моделей изображений Gemini 3 режим "Thinking" включен по умолчанию (в API его нельзя отключить), модель генерирует промежуточные изображения для проверки композиции и логики, эти черновики появляются в `parts` вместе с финальной версией, а "the last image within Thinking is also the final rendered image" (официальная документация: `ai.google.dev/gemini-api/docs/image-generation`). По результатам наших тестов в июле 2026 года (нативный для Google формат `generateContent`): | Сценарий | Возвращаемые изображения | | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | Только text-to-image | Всегда 1 (даже если prompt явно просит "multiple images") | | Простое редактирование изображения (добавить аксессуары / изменить фон / изменить стиль) | Всегда 1 | | Сложное редактирование в формате задачи (например, "4-view character sheet + outfit change + white background" с несколькими ограничениями) | 2–10, стабильно воспроизводится | Триггером является **сложность задачи в prompt**, а не само по себе "image editing". Несколько изображений по-прежнему находятся в **одном candidate** (а не в нескольких candidate), и каждое из них является полноценным изображением — это последовательные черновики процесса Thinking одного и того же дизайна (одна и та же композиция, немного разные детали), и **последняя часть является финальной версией**. Эти черновики возвращаются как обычные image parts (с полем `thoughtSignature`, без флага `thought: true`); в документации Google сказано, что Thinking генерирует максимум два промежуточных изображения, но мы наблюдали до 10 на сложных задачах. **Влияние на тарификацию**: каждое изображение тарифицируется по фиксированному числу token (1120 tokens на изображение при разрешении 1K/2K, 2000 при 4K), поэтому output tokens растут строго линейно с числом изображений. Периодическая запись 6000+ (вплоть до \~13.5k в крайних случаях) output-token в ваших логах — это просто ответ из 4–10 изображений, **а не аномалия тарификации**. **Рекомендуемый downstream code**: ```python theme={null} parts = response["candidates"][0]["content"]["parts"] or [] # parts is null on safety refusals images = [p["inlineData"]["data"] for p in parts if "inlineData" in p] if images: final_image = images[-1] # last one = final version ``` * **Всегда итерируйтесь по parts** — не предполагайте, что в ответе всегда одно изображение; любой учет по изображениям или логика сохранения должны опираться на фактическое число parts * **Берите последнее изображение, если вам нужно только одно**: в более ранних черновиках детали могут быть незавершенными и качество немного ниже, поэтому не выбирайте первое * **Управлять числом изображений через prompt в основном неэффективно** (в тестах инструкции "output only one image" игнорировались) — обрабатывайте это в code * Ответы с несколькими изображениями занимают 35–142s (при разрешении 1K, дольше при большем числе изображений), что заметно дольше, чем ответы с одним изображением — сохраняйте рекомендации по timeout выше (≥ 5 minutes) Полный разбор полей usageMetadata (разница между деталями и итогами, особенность подсчета в ответах с отказом и многое другое) см. в [Поля Usage и объяснение вывода](/ru/api-capabilities/nano-banana-usage-metadata). ## Часто задаваемые вопросы Три ключевых показателя для диагностики неудачных генераций, политики модерации контента и дружественных стратегий prompt Устранение неполадок при неудачных генерациях и частые вопросы Для сбоев, не вызванных вашим вводом, кредиты возмещаются в зависимости от числа неудачных запросов Полный текст ошибки выглядит так: ```text theme={null} [&{{write tcp ip:port->ip:port: write: connection reset by peer Unknown error shell_api_error write_response_body_failed} 500 }] ``` Обычно это вызвано слишком большими загрузками изображений — тело запроса становится слишком большим, и соединение обрывается. Следуйте этим рекомендациям: * **Ограничьте количество изображений**: соблюдайте официальные правила (максимум 14 изображений на prompt — см. официальную спецификацию выше). * **Ограничьте размер каждого изображения**: держите каждое изображение меньше 5MB — официальный лимит на одно изображение составляет 7MB, а base64-кодирование увеличивает размер примерно на 1/3, так что оставляйте запас. * **Сжимайте на frontend перед загрузкой**: сжимайте изображения на frontend (или через серверный relay) перед отправкой в API — распространенная практика: ограничивать длинную сторону, конвертировать в JPEG/WebP и настраивать параметр качества. * **Переключитесь на ввод через URL**: нативный формат Gemini поддерживает передачу image URL через `fileData.fileUri`, полностью обходя слишком большие тела запросов в base64 — см. [Ввод изображения через URL](#url-image-input) выше. ## Сценарии использования * **AI chat-клиенты**: такие клиенты, как [Cherry Studio](/ru/scenarios/chat/cherry-studio), можно настроить для прямой генерации изображений через APIYI * **Тестирование генерации**: быстро проверьте производительность модели в chat-клиенте или консоли ## Расширенные сценарии * **Нужно загружать изображения через URL?** Нативный эндпоинт Gemini поддерживает передачу URL изображения через `fileData.fileUri`; однако режим, совместимый с OpenAI, не поддерживает загрузку по URL, поэтому используйте Base64. См. примеры кода и оговорки в [Ввод изображения по URL](#url-image-input) выше. * **Нужно сразу получать URL для скачивания (вместо Base64)?** Используйте группу NB-OSS — см. [Группа Nano Banana OSS](/ru/api-capabilities/nano-banana-oss-group).