> ## Documentation Index
> Fetch the complete documentation index at: https://polza.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2

> Генерация изображений до 4K — полный API-гайд

Nano Banana 2 (`google/gemini-3.1-flash-image-preview`) — модель генерации и редактирования изображений с поддержкой до 4K разрешения, точным рендерингом текста и возможностью передавать до 8 референс-изображений.

## Характеристики

| Характеристика       | Nano Banana                     | Nano Banana 2                           |
| -------------------- | ------------------------------- | --------------------------------------- |
| ID модели            | `google/gemini-2.5-flash-image` | `google/gemini-3.1-flash-image-preview` |
| Max prompt           | 20 000 символов                 | 20 000 символов                         |
| Разрешения           | —                               | 1K, 2K, 4K                              |
| Aspect ratio         | 10 вариантов                    | 11 вариантов                            |
| Референс-изображения | до 8                            | до 8                                    |

## Примеры

### Редактирование с референс-изображением

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://polza.ai/api/v1/media', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <POLZA_AI_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'google/gemini-3.1-flash-image-preview',
      input: {
        prompt: "Добавь текст 'SALE 50%' крупными буквами в центре",
        image_resolution: '4K',
        images: [
          { type: 'url', data: 'https://example.com/banner.jpg' }
        ]
      }
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://polza.ai/api/v1/media',
      headers={'Authorization': 'Bearer <POLZA_AI_API_KEY>'},
      json={
          'model': 'google/gemini-3.1-flash-image-preview',
          'input': {
              'prompt': "Добавь текст 'SALE 50%' крупными буквами в центре",
              'image_resolution': '4K',
              'images': [
                  {'type': 'url', 'data': 'https://example.com/banner.jpg'}
              ]
          }
      }
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://polza.ai/api/v1/media" \
    -H "Authorization: Bearer <POLZA_AI_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-3.1-flash-image-preview",
      "input": {
        "prompt": "Добавь текст SALE 50% крупными буквами в центре",
        "image_resolution": "4K",
        "images": [
          { "type": "url", "data": "https://example.com/banner.jpg" }
        ]
      }
    }'
  ```
</CodeGroup>

## Ответ

API возвращает объект с ID задачи:

```json theme={null}
{
  "id": "aig_abc123",
  "object": "media.generation",
  "status": "pending",
  "created": 1703001244,
  "model": "google/gemini-3.1-flash-image-preview"
}
```

Опросите статус через `GET /v1/media/{id}`:

```bash theme={null}
curl "https://polza.ai/api/v1/media/aig_abc123" \
  -H "Authorization: Bearer <POLZA_AI_API_KEY>"
```

### Статусы

| Статус       | Описание                                   |
| ------------ | ------------------------------------------ |
| `pending`    | В очереди                                  |
| `processing` | Генерация выполняется                      |
| `completed`  | Готово, URL результата в поле `output.url` |
| `failed`     | Ошибка, описание в поле `error`            |

<Note>
  Результаты хранятся **7 дней**. Для постоянного хранения используйте [Storage API](/api-reference/storage/upload) с политикой `PERMANENT`.
</Note>

## Советы

<AccordionGroup>
  <Accordion title="4K для печати" icon="print">
    Для полиграфии и баннеров выбирайте `image_resolution: "4K"` — это максимальное качество модели.
  </Accordion>

  <Accordion title="Точный рендеринг текста" icon="font">
    Nano Banana 2 хорошо рендерит текст на изображениях. Указывайте шрифт, размер и расположение в промпте.
  </Accordion>

  <Accordion title="Детализируйте освещение" icon="lightbulb">
    Модель отлично обрабатывает сложные световые схемы — описывайте их подробно: студийный свет, боковое освещение, время суток.
  </Accordion>
</AccordionGroup>

## Смотрите также

<CardGroup cols={2}>
  <Card title="Попробовать в Playground" icon="play" href="/dashboard/playground">
    Тестируйте модель прямо в браузере без написания кода
  </Card>

  <Card title="Статус и результат генерации" icon="clock" href="/api-reference/media/status">
    GET /v1/media/\{id} — проверка статуса задачи
  </Card>

  <Card title="Nano Banana" icon="image" href="/gaidy/nanobanano">
    Базовая версия модели
  </Card>

  <Card title="Nano Banana Pro" icon="star" href="/gaidy/nanobanano-pro">
    Продвинутая версия с расширенными возможностями
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/media/nanobanano-2
openapi: 3.0.0
info:
  title: Polza.ai API
  description: AI агрегатор — унифицированный доступ к сотням AI моделей
  version: '1.0'
  contact: {}
servers:
  - url: https://polza.ai/api
    description: Production
security: []
tags: []
paths:
  /v1/media/nanobanano-2:
    post:
      tags:
        - Медиа
      summary: Nano Banana 2 — генерация изображений
      operationId: MediaController_nanobanano2
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  enum:
                    - google/gemini-3.1-flash-image-preview
                  description: ID модели
                  example: google/gemini-3.1-flash-image-preview
                input:
                  $ref: '#/components/schemas/NanoBanana2InputDto'
                provider:
                  $ref: '#/components/schemas/ProviderDto'
                async:
                  type: boolean
                  description: >-
                    Асинхронный режим генерации. При true возвращается taskId
                    для опроса статуса
                  example: false
                  default: false
                user:
                  type: string
                  description: Уникальный идентификатор конечного пользователя
                  example: user-123
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaStatusPresenter'
        '401':
          description: Ошибка авторизации. Проверьте ключ доступа
        '403':
          description: Ошибка доступа. Проверьте права доступа ключа
        '500':
          description: Ошибка сервера. Обратитесь к поставщику услуг
      security:
        - bearer: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST \
              --url https://polza.ai/api/v1/media \
              --header 'Authorization: Bearer <POLZA_AI_API_KEY>' \
              --header 'Content-Type: application/json' \
              --data '{
                "model": "google/gemini-3.1-flash-image-preview",
                "input": {
                  "prompt": "Фотореалистичный портрет бизнесмена в современном офисе",
                  "aspect_ratio": "1:1",
                  "image_resolution": "2K",
                  "output_format": "png"
                }
              }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                'https://polza.ai/api/v1/media',
                headers={'Authorization': 'Bearer <POLZA_AI_API_KEY>'},
                json={
                    'model': 'google/gemini-3.1-flash-image-preview',
                    'input': {
                        'prompt': 'Фотореалистичный портрет бизнесмена в современном офисе',
                        'aspect_ratio': '1:1',
                        'image_resolution': '2K',
                        'output_format': 'png'
                    }
                }
            )
            print(response.json())
        - lang: javascript
          label: TypeScript
          source: |-
            const response = await fetch('https://polza.ai/api/v1/media', {
              method: 'POST',
              headers: {
                'Authorization': 'Bearer <POLZA_AI_API_KEY>',
                'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                model: 'google/gemini-3.1-flash-image-preview',
                input: {
                  prompt: 'Фотореалистичный портрет бизнесмена в современном офисе',
                  aspect_ratio: '1:1',
                  image_resolution: '2K',
                  output_format: 'png'
                }
              })
            });
            const result = await response.json();
components:
  schemas:
    NanoBanana2InputDto:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Текстовое описание желаемого изображения (до 20 000 символов)
          maxLength: 20000
          example: >-
            Фотореалистичный портрет бизнесмена в современном офисе,
            профессиональное студийное освещение
        aspect_ratio:
          type: string
          description: Соотношение сторон
          example: '1:1'
          enum:
            - auto
            - '1:1'
            - '2:3'
            - '3:2'
            - '3:4'
            - '4:3'
            - '4:5'
            - '5:4'
            - '9:16'
            - '16:9'
            - '21:9'
        image_resolution:
          type: string
          description: Разрешение изображения
          enum:
            - 1K
            - 2K
            - 4K
          example: 2K
        output_format:
          type: string
          description: Формат выходного изображения
          enum:
            - png
            - jpeg
          example: png
        images:
          type: array
          description: Референс-изображения для редактирования (до 8 шт.)
          maxItems: 8
          items:
            $ref: '#/components/schemas/MediaFileDto'
    ProviderDto:
      type: object
      properties:
        allow_fallbacks:
          type: boolean
          description: Разрешить использование резервных провайдеров
          example: true
        order:
          description: Упорядоченный список slug провайдеров для использования
          example:
            - OpenAI
            - Anthropic
          type: array
          items:
            type: string
        only:
          description: Список разрешенных slug провайдеров
          example:
            - OpenAI
            - Google
          type: array
          items:
            type: string
        ignore:
          description: Список игнорируемых slug провайдеров
          example:
            - DeepInfra
          type: array
          items:
            type: string
        sort:
          type: string
          description: Критерий сортировки провайдеров
          enum:
            - price
            - throughput
            - latency
          example: price
        max_price:
          description: Максимальные цены для запроса
          allOf:
            - $ref: '#/components/schemas/ProviderMaxPriceDto'
    MediaStatusPresenter:
      type: object
      properties:
        id:
          type: string
          description: Уникальный идентификатор генерации
          example: gen_581761234567890123
        object:
          type: string
          description: Тип объекта
          example: media.generation
        status:
          type: string
          description: Статус генерации
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
          example: pending
        created:
          type: number
          description: Временная метка создания (Unix timestamp)
          example: 1703001234
        model:
          type: string
          description: ID модели, которая генерирует контент
          example: google/gemini-2.5-flash-image
        completed_at:
          type: number
          description: Временная метка завершения (Unix timestamp)
          example: 1703001244
        data:
          description: Данные сгенерированного контента
          oneOf:
            - 819327a8-8547-4a92-95e9-cd7e9c32d1ad
            - edbb6059-caac-4f6b-a77f-f7716017c656
            - 8ce8f630-b785-43e1-ab80-66d1892d1bb7
        usage:
          description: Информация об использовании ресурсов
          allOf:
            - $ref: '#/components/schemas/MediaUsagePresenter'
        error:
          description: Информация об ошибке (если failed)
          allOf:
            - $ref: '#/components/schemas/MediaErrorPresenter'
        content:
          type: string
          description: >-
            Текстовый ответ модели (если вернула текст вместо/вместе с
            изображением)
          example: Банан и яблоко — это фрукты.
        reasoning_summary:
          type: string
          description: Краткое резюме рассуждений модели
          example: Preparing image generation prompt with camera settings...
        warnings:
          description: Предупреждения (неподдерживаемые параметры и т.д.)
          example:
            - >-
              Параметр isEnhance не поддерживается OpenRouter и будет
              проигнорирован
          type: array
          items:
            type: string
      required:
        - id
        - object
        - status
        - created
        - model
    MediaFileDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - url
            - base64
          description: 'Тип данных: url или base64'
          example: url
        data:
          type: string
          description: URL или base64 данные изображения/видео
          example: https://example.com/image.png
      required:
        - type
        - data
    ProviderMaxPriceDto:
      type: object
      properties:
        prompt:
          type: number
          description: Максимальная цена за промпт токены (RUB за миллион токенов)
          example: 10
        completion:
          type: number
          description: Максимальная цена за completion токены (RUB за миллион токенов)
          example: 20
        image:
          type: number
          description: Максимальная цена за изображение (RUB за штуку)
          example: 5
        audio:
          type: number
          description: Максимальная цена за аудио (RUB за миллион токенов)
          example: 15
        request:
          type: number
          description: Максимальная цена за запрос (RUB за запрос)
          example: 1
    MediaUsagePresenter:
      type: object
      properties:
        input_units:
          type: number
          description: Входные единицы (для edit mode)
          example: 1
        output_units:
          type: number
          description: Выходные единицы (сгенерированные)
          example: 1
        duration_seconds:
          type: number
          description: Длительность для видео/аудио (секунды)
          example: 5
        input_tokens:
          type: number
          description: Количество входных токенов
          example: 10
        output_tokens:
          type: number
          description: Количество выходных токенов
          example: 0
        total_tokens:
          type: number
          description: Общее количество токенов
          example: 10
        cost_rub:
          type: number
          description: Стоимость в рублях
          example: 1.5
        cost:
          type: number
          description: Стоимость в рублях (alias для cost_rub)
          example: 1.5
    MediaErrorPresenter:
      type: object
      properties:
        code:
          type: string
          description: Код ошибки (FORBIDDEN, BAD_GATEWAY, REQUEST_TIMEOUT и т.д.)
          example: BAD_GATEWAY
        message:
          type: string
          description: Сообщение об ошибке на русском языке
          example: Ошибка генерации медиа контента
      required:
        - code
        - message
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API Key
      type: http
      description: >-
        API ключ передаётся в заголовке: Authorization: Bearer
        <POLZA_AI_API_KEY>

````