Руководство разработчика по серии Nano Banana

​

Карточки моделей

​

Примеры результатов

​

Управление размером

• Сохранение соотношения сторон исходного изображения: просто не указывайте aspectRatio; при редактировании нескольких изображений приоритет имеет размер последнего изображения
• Разрешение imageSize: поддерживаются 1K / 2K / 4K
  • Nano Banana (Gen 1) поддерживает только 1K
  • Nano Banana 2 добавляет 512px
  • Nano Banana 2 Lite поддерживает только 1K (без 2K/4K/512px)

​

Как интегрировать

​

Официальная документация

• Официальная документация Google: ai.google.dev/gemini-api/docs/image-generation
• Чтобы интегрировать APIYI, просто замените URL запроса + ключ на данные APIYI; все остальные параметры совпадают с официальными

​

Проверка официального статуса (диагностика проблем на стороне вышестоящего сервиса)

​

Поддерживаемые эндпоинты

• Рекомендуемый эндпоинт (нативный Gemini): https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent
• Поддерживаются вызовы через режим, совместимый с OpenAI (/v1/chat/completions; передавайте Base64 или общедоступную ссылку через image_url)
• /v1/image/generations не поддерживается

​

Формат для разработки (рекомендация по умолчанию)

• [Рекомендуется] Используйте формат нативного эндпоинта Google
• Изображения: загружайте в формате Base64, скачивайте и размещайте повторно
• Способ вызова: синхронные многопоточные вызовы; асинхронные вызовы пока не поддерживаются

​

Требования к входным изображениям

• Одно изображение не может превышать 7MB (правило Google); если импорт выполняется через Google Cloud Storage, лимит на каждый файл составляет 30MB
• До 14 изображений на prompt
• Поддерживаемые типы MIME: image/png, image/jpeg, image/webp, image/heic, image/heif (формат jpg уже поддерживается APIYI)
• Увеличение размера при кодировании в Base64: преобразование изображения в Base64 увеличивает его размер примерно на 33.3% (изображение размером 7MB становится примерно 9.3MB)
• Лимит APIYI: общий объем изображений, загруженных в одном запросе, должен быть менее 100MB — все вызовы являются синхронными, а слишком большие payload могут вызвать резкий рост потребления памяти

​

Ввод изображений по URL

​

Требования к подходящей ссылке

​

Формат запроса

{
  "contents": [{
    "role": "user",
    "parts": [
      { "fileData": { "fileUri": "https://your-cdn.example.com/a.png", "mimeType": "image/png" } },
      { "fileData": { "fileUri": "https://your-cdn.example.com/b.jpg", "mimeType": "image/jpeg" } },
      { "text": "Put the jacket from the second image on the person in the first image" }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": { "imageSize": "2K" }
  }
}

• Несколько изображений: по одному fileData на каждое изображение по порядку внутри parts. Их также можно комбинировать с inlineData; в наших тестах два изображения по URL и одно изображение в base64 в рамках одного запроса сгенерировались штатно
• mimeType: укажите реальный формат изображения. В наших тестах текущие маршруты всё равно считывали изображение, даже когда он был указан неверно или отсутствовал, но полагаться на это не стоит
• Имена полей: используйте camelCase fileData / fileUri / mimeType в соответствии с официальной документацией Google. Варианты в snake_case file_data / file_uri в настоящее время также принимаются

​

Проверьте, что референсное изображение действительно прочитано

"promptTokensDetails": [
  { "modality": "TEXT", "tokenCount": 17 },
  { "modality": "IMAGE", "tokenCount": 1120 }
]

​

Как проявляются ошибки загрузки

​

Пример Curl (fileUri)

curl --location 'https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent' \
  --header "Authorization: Bearer $APIYI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
      "contents": [{
          "role": "user",
          "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" }
          ]
      }],
      "generationConfig": {
          "responseModalities": ["IMAGE"],
          "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
      }
  }' > output.json

​

Пример на Python (fileUri)

import base64, os, requests

API_KEY = os.environ["APIYI_API_KEY"]
MODEL = "gemini-3.1-flash-image"
URL = f"https://api.apiyi.com/v1beta/models/{MODEL}:generateContent"

IMAGE_URLS = [
    "https://raw.githubusercontent.com/apiyi-api/ai-pics/refs/heads/main/1762260696217_dd0352c1f9604540.png",
]
PROMPT = "Change the person's clothes to a blue jacket and keep everything else the same"

payload = {
    "contents": [{
        "role": "user",
        "parts": [
            *[{"fileData": {"fileUri": u, "mimeType": "image/png"}} for u in IMAGE_URLS],
            {"text": PROMPT},
        ],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"imageSize": "2K"},
    },
}

resp = requests.post(URL, json=payload, timeout=300,
                     headers={"Authorization": f"Bearer {API_KEY}"})
if resp.status_code != 200:
    raise SystemExit(f"HTTP {resp.status_code}: {resp.text[:500]}")
data = resp.json()

# 1. Confirm the reference image was read: promptTokensDetails must include IMAGE
details = data.get("usageMetadata", {}).get("promptTokensDetails", [])
image_tokens = sum(d.get("tokenCount", 0) for d in details if d.get("modality") == "IMAGE")
if image_tokens == 0:
    print("⚠️ Reference image was not read (Google could not fetch it); the result will ignore it")

# 2. Iterate over parts to find the image; never index into it
for part in data["candidates"][0]["content"]["parts"]:
    inline = part.get("inlineData")
    if inline:
        with open("output.png", "wb") as f:
            f.write(base64.b64decode(inline["data"]))
        print(f"✅ Saved output.png (reference image: {image_tokens} tokens)")
        break
else:
    print("No image in the response:", data["candidates"][0].get("finishReason"))

​

Может ли OpenAI-совместимый эндпоинт принимать URL?

​

Основы тарификации (Важно)

• Длительность синхронного вызова: Pro / 2 при 4K требуют разумного времени генерации примерно 30–150s
• Отключение при тайм-ауте всё равно влечёт начисление платы: например, если генерация занимает 120s, но клиент задаёт тайм-аут 100s и отключается, с вас всё равно взимается плата
• 429 / 503 не тарифицируются: за неудачные запросы плата не взимается (мы стараемся не заставлять клиентов ждать или оставаться без изображения)
• Отказы из-за политики безопасности контента всё равно влекут начисление платы: когда во входных данных клиента есть проблемы с безопасностью контента и Google отказывает в генерации изображения, за код статуса 200 всё равно взимается плата — см. обработку ошибок и план гарантии ниже

​

Google Search grounding is charged on top of the per-call price

{
  "contents": [{ "parts": [{ "text": "A weather card poster for Tokyo today" }] }],
  "tools": [{ "googleSearch": {} }]
}

​

thinkingLevel не влияет на Pro — не копируйте его из NB2

• Не вызывает ошибку — запрос нормально возвращает 200
• Но не влияет: измеренные значения thoughtsTokenCount находились в диапазоне 108–156, полностью перекрывая диапазон 130–159, наблюдаемый без параметра
• Рассуждение в Pro всегда включено и не подлежит настройке, как прямо указано в документации Google

​

Настройки таймаута (Важно)

API Connection Error: HTTPSConnectionPool(host='api.apiyi.com', port=443): Read timed out. (read timeout=120)

timeout = {
    "1K": 300,  # 5 minutes - quick preview
    "2K": 300,  # 5 minutes - recommended
    "4K": 600,  # 10 minutes - ultra HD
}

​

Многошаговое редактирование в диалоге (поддерживается нативно; обратные модели — нет)

import requests, base64

API_KEY = "sk-your-api-key"
URL = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image: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

​

Всегда перебирайте parts, чтобы получить изображение — никогда не индексируйте его

cand = (resp.get("candidates") or [{}])[0]
parts = (cand.get("content") or {}).get("parts") or []      # handles parts=null
images = [p["inlineData"] for p in parts if "inlineData" in p]
if not images:
    raise RuntimeError(f"No image returned, finishReason={cand.get('finishReason')}")

final = images[-1]                                 # last one is the final version
image_bytes = base64.b64decode(final["data"])
mime = final["mimeType"]                           # trust the response; don't hardcode image/png

const parts = resp?.candidates?.[0]?.content?.parts ?? [];
const images = parts.filter((p) => p.inlineData?.data);   // ✅ never write parts[1]
if (images.length === 0) throw new Error("Gemini returned no image data");
const { data, mimeType } = images[images.length - 1].inlineData;   // last is the final version

​

Почему ответы иногда содержат несколько изображений

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

• Всегда итерируйтесь по частям — не предполагайте, что на каждый ответ приходится одно изображение; любая логика подсчёта или сохранения по изображениям должна опираться на фактическое количество частей
• Берите последнее изображение, если нужно только одно: более ранние черновики имеют незавершённые детали и немного более низкое качество, поэтому не выбирайте первое
• Управление количеством изображений через prompt в основном неэффективно (в тестировании инструкции вроде «выведи только одно изображение» игнорировались) — обрабатывайте это в коде
• Ответы с несколькими изображениями занимают 35–142 с (при разрешении 1K, дольше при большем числе изображений), заметно больше, чем ответы с одним изображением — сохраняйте рекомендации по тайм-ауту выше (≥ 5 минут)

​

Часто задаваемые вопросы

[&{{write tcp ip:port->ip:port: write: connection reset by peer Unknown error shell_api_error  write_response_body_failed} 500 }]

​

Сценарии использования

• Клиенты AI-чатов: такие клиенты, как Cherry Studio, можно настроить для генерации изображений напрямую через APIYI
• Проверка генерации: быстро проверьте производительность модели в чат-клиенте или в консоли

​

Расширенные сценарии

• Хотите загружать изображения по URL? Используйте fileData.fileUri на нативном эндпоинте Gemini или image_url на OpenAI-совместимом эндпоинте. Серверы Google скачивают изображение, поэтому хост имеет значение. Требования к ссылкам, способы обнаружения ошибок загрузки и примеры кода см. в разделе Ввод изображений по URL выше.
• Хотите получать URL для скачивания напрямую (вместо Base64)? Используйте группу NB-OSS — см. Группа Nano Banana OSS.