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.

Ідемпотентність запитів не підтримується. Кожен коректний запит 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",
  "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"
  }
}'

Із зображення в зображення

Для редагування зображень установіть параметр 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",
  "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,
  "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",
  "credits": 2,
  "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",
  "credits": 2,
  "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",
  "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) використовується структура відповіді на запит статусу завдання. Сповіщення про збій із поверненням коштів також містять параметр верхнього рівня credits_refunded. Використовуйте id для ідентифікації завдання та status, щоб відрізнити успішно завершені завдання від тих, що зазнали збою. Сповіщення можуть дублюватися: обробляйте їх ідемпотентно за id та status. Зворотні виклики не підписуються цифровим підписом — перевіряйте статус завдання за допомогою автентифікованого запиту до кінцевої точки (endpoint). Помилка доставки сповіщення не скасовує оплату за успішно виконане завдання.

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

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "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",
  "credits": 2,
  "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": 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."
  }
}

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