Nano Banana API

Возможности

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

Each image costs 2 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

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

Создайте 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.

Тело запроса

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

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

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

Отправьте этот минимальный запрос, сохраните полученный 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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

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

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

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

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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

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

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

Замените демонстрационные медиа-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",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "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",
  "credits": 2,
  "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",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

Вебхуки

Укажите 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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

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

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 2
}

Пример обработчика (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."
  }
}

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

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

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

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

Image and video creation requests share the same API key rate limit.

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."
  }
}