Nano Banana 2.1 API

Kemampuan

Harga & kredit

Setiap permintaan menghasilkan satu gambar. Kredit bergantung pada resolusi di bawah. Kredit dicadangkan saat diterima, ditagih saat berhasil, dan dikembalikan jika gagal.

Idempotensi permintaan tidak didukung. Setiap POST yang valid akan membuat tugas berbayar baru. Jika hasil pengiriman belum pasti, lakukan kueri pada taskId yang dikembalikan; mencoba ulang POST dapat membuat tugas baru lainnya.

Autentikasi

Buat kunci API di dasbor. Kunci lengkap hanya akan ditampilkan sekali. Simpan di server Anda dan kirimkan sebagai Bearer token pada setiap permintaan.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Atur variabel lingkungan SEEVIO_API_KEY sebelum menjalankan contoh ini. Contoh JavaScript dijalankan di server Anda menggunakan Node.js; contoh Python menggunakan paket requests.

Isi permintaan

Parameter input

Rasio aspek default diatur ke auto. Setiap permintaan menghasilkan tepat satu gambar.

Mulai cepat

Kirim permintaan minimal ini, simpan taskId yang dikembalikan, lalu gunakan contoh kueri tugas di bawah ini. Nilai kredit dalam respons pembuatan adalah jumlah yang dicadangkan.

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

Contoh respons pembuatan tugas

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

Teks ke gambar

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

Gambar ke gambar

Untuk pengeditan gambar, atur generation_type ke image-to-image dan cantumkan image_urls. Parameter lainnya menggunakan ketentuan yang sama.

Ganti URL media example.com dengan file HTTPS Anda sendiri yang dapat diakses publik. URL contoh ini hanya menunjukkan struktur permintaan dan bukan aset sampel yang dapat diunduh.

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"
    ]
  }
}'

Kueri tugas

Ganti ID contoh dengan taskId yang dikembalikan oleh pembuatan. Kueri hanya mengembalikan tugas milik pengguna dari kunci API tersebut; ID yang tidak dapat diakses atau tidak dikenal akan mengembalikan HTTP 404.

Lakukan polling setiap 10–20 detik sebagai permulaan, kurangi frekuensi pada HTTP 429, dan hentikan saat status telah selesai atau gagal. Gunakan webhook untuk produksi. Setiap contoh kode di bawah ini melakukan satu kueri.

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

Dalam antrean

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

Selesai

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

Gagal

Ketika kueri mengembalikan status=failed, proses pembuatan gambar gagal. Lihat failed_reason untuk mengetahui penyebabnya dan billing_status untuk hasil pengembalian dana. Pada contoh ini, refunded berarti kredit telah dikembalikan. credits tetap menampilkan jumlah awal yang dicadangkan, dan respons tidak menyertakan 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."
}

Tautan hasil tersedia selama 30 hari setelah penyimpanan. Setelah masa kedaluwarsa habis, results akan kosong.

Webhook

Atur callback_url dalam permintaan buat untuk menerima POST JSON saat tugas selesai atau gagal. Kembalikan respons 2xx dalam waktu 15 detik. Pengiriman yang gagal akan dicoba kembali; proses pengiriman berulang secara idempoten berdasarkan ID tugas.

Endpoint callback Anda harus menerima permintaan POST dengan body permintaan JSON (Content-Type: application/json).

Buat tugas dengan callback

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

Panggilan balik (callback) menggunakan struktur respons kueri tugas; notifikasi kegagalan yang dananya dikembalikan juga menyertakan credits_refunded tingkat atas. Gunakan id untuk mengidentifikasi tugas dan status untuk membedakan antara tugas yang selesai dan gagal. Notifikasi dapat terkirim berulang kali: proses secara idempoten berdasarkan id dan status. Panggilan balik tidak ditandatangani; verifikasi tugas menggunakan titik akhir (endpoint) kueri yang terautentikasi. Kegagalan pengiriman notifikasi tidak menyebabkan pengembalian dana untuk tugas yang berhasil.

Tugas selesai: payload callback sukses

created_at adalah waktu pembuatan peristiwa; task_created_at adalah waktu pembuatan tugas, dalam detik Unix. Contoh menampilkan kolom yang disarankan; respons dapat memuat kolom tambahan.

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

Tugas gagal: payload callback gagal

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

Contoh penerima

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 });
}

Contoh Next.js ini membaca body callback JSON dan menangani tugas yang berhasil serta gagal secara langsung. Tambahkan persistensi dan deduplikasi ID tugas untuk aplikasi Anda; antrekan pekerjaan yang lambat sebelum mengonfirmasi callback.

Error

Error HTTP memiliki objek error dengan kode dan pesan. Tugas yang berhasil diterima masih bisa gagal nanti; kueri tugas atau tangani callback kegagalannya.

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

Error menggunakan error.code dan error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Error 402 insufficient_credits berarti kredit Anda yang tersedia tidak mencukupi untuk permintaan ini.

Batas frekuensi

Membuat tugas: secara default, setiap kunci API mengizinkan hingga 100 permintaan per menit. Batas frekuensi kustom saat ini belum tersedia.

Kueri tugas: secara default, setiap kunci API mengizinkan hingga 120 permintaan per menit. Permintaan kueri dan permintaan pembuatan tugas dihitung secara terpisah.

Permintaan pembuatan gambar dan video berbagi batas tingkat (rate limit) kunci API yang sama.

HTTP 429 menyertakan Retry-After: 60 untuk pembuatan dan Retry-After: 5 untuk kueri. Gunakan backoff dan hindari polling lebih sering dari yang diperlukan.

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

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