Техническая документация: NanoBanana API

1. Обзор NanoBanana API

NanoBanana API — это мощный инструмент для генерации и редактирования изображений с использованием искусственного интеллекта. API предоставляет возможность создавать уникальные изображения по текстовым описаниям или редактировать существующие изображения на основе промптов.

2. Аутентификация

2.1 Получение API-ключа

Все запросы к NanoBanana API требуют аутентификации через Bearer Token.

1. Перейдите на страницу управления API-ключами
2. Создайте новый API ключ или используйте существующий
3. Скопируйте ключ для использования в вашем приложении

2.2 Безопасность API-ключа

Authorization: Bearer YOUR_API_KEY

3. Быстрый старт

3.1 Базовый пример на cURL

curl -X POST "https://api.nanobananaapi.ai/api/v1/nanobanana/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Красивый закат над горами",
    "type": "TEXTTOIAMGE",
    "numImages": 1,
    "callBackUrl": "https://your-callback-url.com/webhook"
  }'

3.2 Ответ сервера

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}

4. Генерация изображений

4.1 Текст → Изображение (TEXTTOIAMGE)

Создание новых изображений на основе текстового описания:

• Установите параметр type в значение "TEXTTOIAMGE"
• Укажите детальное описание в параметре prompt
• Задайте количество изображений (1-4) в параметре numImages

4.2 Изображение → Изображение (IMAGETOIAMGE)

Редактирование существующих изображений:

• Установите параметр type в значение "IMAGETOIAMGE"
• Укажите URL исходных изображений в массиве imageUrls
• Опишите желаемые изменения в параметре prompt

5. Callback-уведомления

5.1 Формат callback-запроса

После завершения обработки задачи система отправляет POST-запрос на указанный callBackUrl:

{
  "msg": "Image generated successfully.",
  "code": 200,
  "data": {
    "taskId": "9e4286b7b27960dfeb8e1d279b50b28d",
    "info": {
      "resultImageUrl": "https://tempfile.aiquickdraw.com/r/9e4286b7b27960dfeb8e1d279b50b28d_1756467493.jpg"
    }
  }
}

5.2 Пример обработчика callback на Node.js

const express = require('express');
const app = express();

app.use(express.json());

app.post('/nanobanana-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received callback:', {
    taskId: data.taskId,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    console.log('Generation successful!');
    console.log('Image URL:', data.info.resultImageUrl);
  } else if (code === 400) {
    console.log('Content policy violation');
  } else if (code === 500) {
    console.log('Internal error');
  } else if (code === 501) {
    console.log('Generation failed');
  }
  
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});

6. Статус задач

6.1 Коды статуса задач

6.2 Polling запросы

Если вы не используете callback-уведомления, можно отслеживать статус задачи через polling:

curl -X GET "https://api.nanobananaapi.ai/api/v1/nanobanana/record-info?taskId=task12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Рекомендуется проверять статус каждые 30 секунд.

7. Параметры API

7.1 Обязательные параметры

7.2 Опциональные параметры

Поддерживаемые форматы изображений:

• 1:1 - Квадратное
• 9:16 - Портретное (мобильное)
• 16:9 - Ландшафтное (широкоэкранное)
• 3:4 - Портретное
• 4:3 - Ландшафтное (традиционное)
• 3:2 - Ландшафтное (фото)
• 2:3 - Портретное (фото)

8. Примеры кода

8.1 JavaScript/Node.js класс

class NanoBananaAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.nanobananaapi.ai/api/v1/nanobanana';
  }
  
  async generateImage(prompt, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        type: options.type || 'TEXTTOIAMGE',
        numImages: options.numImages || 1,
        callBackUrl: options.callBackUrl,
        watermark: options.watermark,
        imageUrls: options.imageUrls
      })
    });
    
    const result = await response.json();
    if (!response.ok || result.code !== 200) {
      throw new Error(`Generation failed: ${result.msg || 'Unknown error'}`);
    }
    
    return result.data.taskId;
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    return await response.json();
  }
}

// Использование
const api = new NanoBananaAPI('YOUR_API_KEY');
const taskId = await api.generateImage('Пейзаж горного озера на закате');
console.log('Task ID:', taskId);

8.2 Python пример

import requests
import time

class NanoBananaAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.nanobananaapi.ai/api/v1/nanobanana"
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
    
    def generate_image(self, prompt, **kwargs):
        data = {
            "prompt": prompt,
            "type": kwargs.get("type", "TEXTTOIAMGE"),
            "numImages": kwargs.get("numImages", 1),
            "callBackUrl": kwargs.get("callBackUrl", ""),
            "watermark": kwargs.get("watermark", ""),
            "imageUrls": kwargs.get("imageUrls", []),
            "image_size": kwargs.get("image_size", "1:1")
        }
        
        response = requests.post(
            f"{self.base_url}/generate",
            headers=self.headers,
            json=data
        )
        
        result = response.json()
        if response.status_code != 200 or result.get("code") != 200:
            raise Exception(f"Generation failed: {result.get('msg')}")
        
        return result["data"]["taskId"]
    
    def get_task_status(self, task_id):
        response = requests.get(
            f"{self.base_url}/record-info?taskId={task_id}",
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
        
        return response.json()

# Использование
api = NanoBananaAPI("YOUR_API_KEY")
task_id = api.generate_image(
    "Космический корабль в небе над городом будущего",
    numImages=2,
    image_size="16:9"
)
print(f"Task created: {task_id}")

9. NanoBanana Pro

NanoBanana Pro предоставляет расширенные возможности генерации изображений:

• Поддержка разрешений до 4K
• Расширенный набор параметров
• Поддержка до 8 исходных изображений
• Автоматическое определение соотношения сторон

POST /api/v1/nanobanana/generate-pro

{
  "prompt": "Реалистичный портрет человека в стиле киберпанк",
  "resolution": "2K",
  "aspectRatio": "16:9",
  "callBackUrl": "https://your-callback.com/webhook",
  "imageUrls": ["https://example.com/reference.jpg"]
}

10. Рекомендации по использованию

10.1 Оптимизация промптов

• Используйте конкретные и детальные описания
• Указывайте стиль изображения (фотография, рисунок, 3D-рендер и т.д.)
• Добавляйте информацию об освещении, перспективе, настроении
• Тестируйте разные формулировки для получения лучших результатов

10.2 Обработка callback-уведомлений

• Используйте HTTPS для callback URL
• Реализуйте идемпотентную обработку (один taskId может получить несколько callback)
• Обрабатывайте ответ сервера быстро (в течение 15 секунд)
• Скачивайте сгенерированные изображения сразу после получения callback

10.3 Управление ошибками

• Реализуйте retry-логику для сетевых ошибок
• Обрабатывайте все возможные коды ошибок (400, 500, 501)
• Логируйте ошибки для последующего анализа

11. Обработка ошибок

11.1 Коды ошибок API

11.2 Обработка callback ошибок

// В callback обработчике
app.post('/callback', (req, res) => {
  const { code, msg } = req.body;
  
  switch(code) {
    case 400:
      console.error('Content policy violation:', msg);
      // Отправьте уведомление пользователю
      break;
    case 500:
      console.error('Server error:', msg);
      // Запланируйте повторную попытку
      break;
    case 501:
      console.error('Generation failed:', msg);
      // Сообщите пользователю об ошибке
      break;
  }
  
  res.status(200).json({ received: true });
});

12. Кредиты аккаунта

Каждый аккаунт имеет определенное количество кредитов для использования API. Кредиты расходуются в зависимости от типа и сложности запроса.

12.1 Проверка баланса

curl -X GET "https://api.nanobananaapi.ai/api/v1/common/credit" \
  -H "Authorization: Bearer YOUR_API_KEY"

12.2 Ответ сервера

{
  "code": 200,
  "msg": "success",
  "data": 150  // Остаток кредитов
}

13. Поддержка и ресурсы

13.1 Контактная информация

• Техническая поддержка: support@nanobanana.com
• Документация: https://docs.nanobananaapi.ai
• API Endpoint: https://api.nanobananaapi.ai

13.2 Полезные ссылки

• Навигация по документации
• Управление API-ключами
• Статус сервиса