Nano Banana 2.1 API

Возможности

Тарифы и кредиты

Каждый запрос создаёт одно изображение. Стоимость в кредитах зависит от разрешения в таблице ниже. Кредиты резервируются при принятии задачи, списываются при успехе и возвращаются при ошибке.

Идемпотентность запросов не поддерживается. Каждый корректный запрос POST создает новую тарифицируемую задачу. Если результат отправки неизвестен, проверьте статус по возвращенному taskId. Повторная отправка POST может привести к созданию дублирующей задачи.

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

Создайте API-ключ в панели управления. Полный ключ показывается только один раз. Храните его на своём сервере и передавайте в качестве Bearer-токена в заголовке каждого запроса.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Задайте переменную окружения SEEVIO_API_KEY перед запуском этих примеров. Примеры на JavaScript выполняются на стороне сервера с помощью Node.js; примеры на Python используют библиотеку requests.

Тело запроса

Входные параметры

Соотношение сторон по умолчанию имеет значение auto. Каждый запрос генерирует ровно одно изображение.

Быстрый старт

Отправьте этот минимальный запрос, сохраните полученный taskId, а затем используйте пример запроса статуса ниже. Значение credits в ответе на создание задачи — это зарезервированная сумма.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2-1",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Пример ответа при создании задачи

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 3
}

Из текста в изображение

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2-1",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Из изображения в изображение

Для редактирования изображений установите параметр generation_type в значение image-to-image и передайте массив image_urls. Все остальные параметры используют тот же контракт.

Замените демонстрационные медиа-URL example.com своими собственными публично доступными HTTPS-файлами. Примеры URL служат лишь для демонстрации структуры запроса и не являются скачиваемыми ресурсами.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2-1",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Запрос статуса задачи

Замените ID в примере на taskId, полученный при создании. Запросы возвращают только те задачи, которые принадлежат владельцу API-ключа; недоступные или несуществующие ID возвращают HTTP 404.

Для начала делайте запросы каждые 10–20 секунд, увеличивайте интервал при получении HTTP 429 и прекращайте опрос, когда статус изменится на completed или failed. Для продакшена рекомендуется использовать вебхуки. Каждый пример кода ниже выполняет один запрос.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

В очереди

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Завершено

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Ошибка

Если запрос возвращает status=failed, генерация завершилась неудачно. Причину ошибки можно узнать в failed_reason, а статус возврата средств — в billing_status. В данном примере значение refunded означает, что кредиты были возвращены на баланс. При этом в credits отображается изначально зарезервированная сумма, а блок data в ответе отсутствует.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Ссылки на результаты доступны в течение 30 дней после сохранения. По истечении этого срока массив results будет пуст.

Вебхуки

Укажите callback_url в запросе на создание задачи, чтобы получать POST-запросы с JSON-телом при завершении или ошибке задачи. Возвращайте ответ со статусом 2xx в течение 15 секунд. В случае неудачной доставки попытки повторяются; обрабатывайте повторные доставки идемпотентно по ID задачи.

Ваша конечная точка (endpoint) для обратного вызова должна принимать POST-запросы с телом запроса в формате JSON (Content-Type: application/json).

Создание задачи с вебхуком

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2-1",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Вебхуки используют структуру ответа для запроса задачи. Уведомления о сбоях с возвратом средств также содержат поле credits_refunded на верхнем уровне. Используйте id для идентификации задачи и status для определения её успешного завершения или сбоя. Уведомления могут приходить повторно: обрабатывайте их идемпотентно по id и status. Вебхуки не имеют цифровой подписи; проверяйте статус задачи через аутентифицированную конечную точку запроса. Сбой доставки уведомления не приводит к возврату средств за успешно выполненную задачу.

Задача выполнена: структура успешного ответа (callback payload)

created_at — время создания события, task_created_at — время создания задачи, в секундах Unix. Примеры показывают рекомендуемые поля; ответ может содержать дополнительные поля.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Ошибка выполнения задачи: структура ответа при сбое

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 3
}

Пример обработчика (receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

В этом примере для Next.js показано, как считывать JSON-тело вебхука и обрабатывать успешно выполненные и проваленные задачи. Для интеграции в продакшн добавьте сохранение данных в БД и дедупликацию по task-ID, а ресурсоемкие фоновые задачи отправляйте в очередь перед отправкой ответа на вебхук.

Ошибки

Ошибки HTTP возвращают объект error с полями code и message. Успешно принятая задача всё ещё может завершиться ошибкой позже; запрашивайте статус задачи или обрабатывайте вебхук об ошибке.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Ошибки содержат коды error.code и сообщения error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Ошибка 402 insufficient_credits означает, что на вашем балансе недостаточно кредитов для выполнения этого запроса.

Лимиты запросов

Создание задач: по умолчанию для каждого API-ключа разрешено до 100 запросов в минуту. Индивидуальные лимиты запросов на данный момент не поддерживаются.

Получение информации о задачах: по умолчанию для каждого API-ключа разрешено до 120 запросов в минуту. Запросы на получение информации и запросы на создание задач учитываются раздельно.

Запросы на создание изображений и видео используют общий лимит частоты запросов для одного API-ключа.

HTTP 429 возвращает заголовок Retry-After: 60 для создания задач и Retry-After: 5 для запросов статуса. Используйте экспоненциальную задержку и избегайте избыточного опроса.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}