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.

Замініть адреси медіафайлів 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 завдання.

Ваша кінцева точка зворотного виклику (callback 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.

Завдання виконано: дані успішного зворотного виклику

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
}

Приклад обробника

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 та безпосередньо обробляє успішно виконані й невдалі завдання. Додайте у свій додаток збереження даних та дедуплікацію за 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."
  }
}