# Подключение к Google AI (Gemini image-gen / "nanobanana 2")

## Что это

Картинки в этом наборе сделаны прямым вызовом Gemini image-generation API от
Google (модель-поколение, которое в команде называют "nanobanana 2"). Это НЕ
Google AI Studio как веб-интерфейс для чата — это программный вызов той же
модели, с реальными референс-фото на входе и одним детальным текстовым
промптом.

- Эндпоинт: `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent`
- Модель по умолчанию: `gemini-3-pro-image` (основная), автоматический
  фоллбек на `gemini-3.1-flash-image`, если основная недоступна/лимит.
- Авторизация: заголовок `x-goog-api-key: <ключ>`.
- На вход можно подать до 3 референс-изображений (`inlineData`, base64) +
  один текстовый промпт — модель использует фото как стилевой якорь, а не
  просто описание.
- На выходе: изображение (+ иногда текст), которое `tools/generate_image.py`
  центр-кропает в квадрат и сохраняет как JPEG ≤ ~900 КБ.

## Ключ

**Ключ для тестов пришёл вам отдельно — в тексте Slack-сообщения, не в этом
архиве.** Так сделано специально: архив можно передавать свободнее, а ключ —
только через приватное сообщение.

1. Создай папку `keys/` рядом с этим файлом (если её ещё нет).
2. Создай файл `keys/smm_gemini_api_key.txt`, вставь туда ключ ОДНОЙ строкой,
   без кавычек, без пробелов вокруг.
3. Никогда не коммить этот файл в git и не публикуй его в открытых каналах —
   он привязан к биллингу Google. Ключ тестовый и будет ротирован после
   проверки; если генерация вдруг перестанет работать с ошибкой авторизации —
   попроси у Романа новый.

### Известная проблема: `429 quota exceeded` на тестовом ключе

Тестовый ключ на момент сборки этого набора стабильно отдаёт `429` с текстом
"You exceeded your current quota, please check your plan and billing details"
на КАЖДЫЙ запрос генерации (проверено на обеих моделях). Это не баг
`generate_image.py` и не ошибка в твоей настройке — на ключе либо не включён
биллинг, либо нулевая квота.

**Что делать**: попроси рабочий ключ у **Alexey Polennikov** в Slack — можно
отправить ему этот текст:

> Привет, Алексей! Работаю с SMM-набором для Swipix (генерация картинок через
> Gemini image-gen, модели gemini-3-pro-image / gemini-3.1-flash-image).
> Тестовый ключ, который мне дали, каждый раз отдаёт 429 quota exceeded —
> похоже, на нём не включён биллинг или лимит нулевой. Можешь выдать рабочий
> ключ с квотой на generateContent, либо подключить биллинг на этот? Спасибо!

Когда придёт новый ключ — просто перезапиши его в `keys/smm_gemini_api_key.txt`
и повтори генерацию.

## Как использовать ключ

```bash
pip install -r tools/requirements.txt

python tools/generate_image.py \
  --prompt "твой mega-prompt текстом..." \
  --ref images/brand-style-refs/fashion-editorial/ref-fashion-03.jpg \
  --out my_test.jpg
```

Или через Claude Code — просто попроси: "сгенерируй картинку по этому
промпту, вот референс-фото" — Claude сам вызовет `tools/generate_image.py`.

## Как получить СВОЙ ключ (после ротации тестового)

1. https://aistudio.google.com/ → войти аккаунтом Google → **Get API key**.
2. Создать новый ключ в проекте с включённым биллингом (image-gen — платная
   модель, бесплатного тира на нужный объём не хватит).
3. Убедиться, что модели `gemini-3-pro-image` / `gemini-3.1-flash-image`
   доступны твоему аккаунту (иногда новые модели раскатываются не на все
   регионы/тиры сразу — если получаешь 404 на модель, попробуй только
   `gemini-3.1-flash-image`).
4. Положить новый ключ в `keys/smm_gemini_api_key.txt` тем же способом.

## Частые проблемы

| Симптом | Причина | Что делать |
|---|---|---|
| HTTP 400 с `imageSize` в тексте ошибки | Модель не поддерживает `imageSize` в `imageConfig` | Скрипт сам делает retry без этого поля — если сообщение повторяется, обновись до последней версии `generate_image.py` |
| HTTP 429 / 500 / 503 | Лимит запросов / временная перегрузка Google | Скрипт сам делает retry с задержкой (до ~2 мин суммарно); если не помогло — попробуй позже |
| Ответ пришёл без картинки (только текст) | Модель отказалась генерить — часто из-за политики безопасности | Скрипт сам смягчает промпт и повторяет; если не помогает — убери из промпта всё похожее на реальные бренды/лица знаменитостей/насилие |
| Картинка не квадратная | Известный баг: `aspectRatio` в `imageConfig` не всегда доходит до модели идеально | `generate_image.py` всегда добивает результат центр-кропом до 1:1 — так в архиве уже сделаны все 10 approved-картинок |
