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. Для всіх інших параметрів діють ті самі правила.

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

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

Для зворотних викликів (callbacks) використовується структура відповіді на запит статусу завдання. Сповіщення про збій із поверненням коштів також містять параметр верхнього рівня credits_refunded. Використовуйте id для ідентифікації завдання та status, щоб відрізнити успішно завершені завдання від тих, що зазнали збою. Сповіщення можуть дублюватися: обробляйте їх ідемпотентно за id та status. Зворотні виклики не підписуються цифровим підписом — перевіряйте статус завдання за допомогою автентифікованого запиту до кінцевої точки (endpoint). Помилка доставки сповіщення не скасовує оплату за успішно виконане завдання.

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

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
}

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

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

Помилки містять 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."
  }
}