---
name: laozhang-api
description: "LaoZhang AI API для генерации изображений. Используй ВСЕГДА при работе с Nano Banana Pro, Gemini 3 Pro, image generation. Активируется на: 'nano banana', 'image generation', 'laozhang', 'сгенерировать картинку', 'баннер', 'thumbnail', 'обложка'."
$ARGUMENTS: "Промпт-описание желаемого изображения или команда (generate, setup, troubleshoot)"
---

# LaoZhang API — Image Generation

## ⚠️ КРИТИЧНО: Правильный Endpoint

**НЕ ИСПОЛЬЗОВАТЬ:**
```
❌ /v1/chat/completions с model: "gemini-2.5-flash-image"
❌ /v1/images/generations
```

**ИСПОЛЬЗОВАТЬ:**
```
✅ /v1beta/models/gemini-3-pro-image-preview:generateContent
```

---

## API Credentials

```bash
API_KEY="YOUR_LAOZHANG_API_KEY"
BASE_URL="https://api.laozhang.ai"
```

---

## Модели для генерации изображений

| Модель | Endpoint | Возможности | Цена |
|--------|----------|-------------|------|
| **gemini-3-pro-image-preview** | `/v1beta/models/gemini-3-pro-image-preview:generateContent` | 4K, aspect ratio, референсы | $0.05/шт |
| gemini-2.5-flash-image | `/v1/chat/completions` | Базовая генерация | Дешевле |
| sora_image | `/v1/chat/completions` | Простая генерация | $0.01/шт |

**Для качественных баннеров/обложек — ТОЛЬКО gemini-3-pro-image-preview!**

---

## Формат запроса для Gemini 3 Pro

### Без референсов (text-to-image)

```bash
curl -X POST "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "PROMPT HERE"}]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "4K"
      }
    }
  }'
```

### С референсами (identity preservation)

```bash
curl -X POST "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "BASE64_ENCODED_IMAGE"
          }
        },
        {"text": "PROMPT WITH [image1] REFERENCE"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "4K"
      }
    }
  }'
```

---

## Параметры imageConfig

| Параметр | Значения | По умолчанию |
|----------|----------|--------------|
| `aspectRatio` | "1:1", "3:4", "4:3", "9:16", "16:9" | auto |
| `imageSize` | "1K", "2K", "4K" | "2K" |

**Для баннеров:** `"aspectRatio": "16:9", "imageSize": "4K"` → 5504×3072
**Для каруселей:** `"aspectRatio": "3:4", "imageSize": "4K"` → 2880×3840

---

## Парсинг ответа

```python
import json, base64

response = requests.post(...)
data = response.json()

# Извлечение base64 картинки
b64 = data['candidates'][0]['content']['parts'][0]['inlineData']['data']
img_bytes = base64.b64decode(b64)

with open('output.png', 'wb') as f:
    f.write(img_bytes)
```

---

## Python Template

```python
import base64
import requests

API_KEY = "YOUR_LAOZHANG_API_KEY"
ENDPOINT = "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image-preview:generateContent"

def generate_image(prompt, references=None, aspect_ratio="16:9", size="4K", output_path="/tmp/output.png"):
    """
    Генерация изображения через Gemini 3 Pro.
    
    Args:
        prompt: Текстовый промпт
        references: Список путей к референсным изображениям
        aspect_ratio: "1:1", "3:4", "4:3", "9:16", "16:9"
        size: "1K", "2K", "4K"
        output_path: Путь для сохранения
    """
    parts = []
    
    # Добавляем референсы
    if references:
        for ref_path in references:
            with open(ref_path, "rb") as f:
                b64 = base64.b64encode(f.read()).decode()
            mime = "image/png" if ref_path.endswith(".png") else "image/jpeg"
            parts.append({
                "inline_data": {
                    "mime_type": mime,
                    "data": b64
                }
            })
    
    # Добавляем промпт
    parts.append({"text": prompt})
    
    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "contents": [{"parts": parts}],
            "generationConfig": {
                "responseModalities": ["IMAGE"],
                "imageConfig": {
                    "aspectRatio": aspect_ratio,
                    "imageSize": size
                }
            }
        },
        timeout=180
    )
    
    data = response.json()
    b64 = data['candidates'][0]['content']['parts'][0]['inlineData']['data']
    img_bytes = base64.b64decode(b64)
    
    with open(output_path, 'wb') as f:
        f.write(img_bytes)
    
    return output_path, len(img_bytes)

# Пример использования
if __name__ == "__main__":
    path, size = generate_image(
        prompt="Professional banner with businessman on right side...",
        references=["/path/to/reference.png"],
        aspect_ratio="16:9",
        size="4K"
    )
    print(f"Saved: {path} ({size//1024}KB)")
```

---

## Bash Script (готовый)

Расположение: `tools/laozhang-image.sh`

```bash
# Простая генерация
./laozhang-image.sh "prompt" --pro --ratio 16:9 --4k --output /tmp/result.png

# С референсами — использовать gen-thumbnail.sh как пример
```

---

## Референсы Identity Kit

При генерации с человеком ВСЕГДА использовать Identity Kit:

| Проект | Путь | Главный референс |
|--------|------|------------------|
| **Твой проект** | `./avatars/` | `your-avatar.png` |

**Identity Lock обязателен в промпте!**

---

## Timing

- Генерация 2K: 25-45 секунд
- Генерация 4K: 40-70 секунд
- **НЕ убивать процесс раньше 180 секунд!**

---

## Troubleshooting

| Проблема | Причина | Решение |
|----------|---------|---------|
| Вертикальное вместо 16:9 | Неправильный endpoint | Использовать `/v1beta/models/gemini-3-pro-image-preview:generateContent` |
| 429 upstream error | Rate limit | Подождать 30 сек и повторить |
| Invalid token | Неправильный ключ | Использовать `sk-2iIu...` |
| Маленькое разрешение | Нет imageSize | Добавить `"imageSize": "4K"` |

---

## Чек-лист перед генерацией

- [ ] Endpoint: `/v1beta/models/gemini-3-pro-image-preview:generateContent`
- [ ] API Key: `YOUR_LAOZHANG_API_KEY`
- [ ] imageConfig с aspectRatio и imageSize
- [ ] Референс через Identity Kit (если нужен человек)
- [ ] Identity Lock в промпте
- [ ] Timeout ≥ 180 секунд