Nano Banana 2.1 API

Keupayaan

Harga & kredit

Setiap permintaan menghasilkan satu imej. Kredit bergantung pada resolusi di bawah. Kredit diperuntukkan semasa diterima, dicaj apabila berjaya dan dipulangkan jika gagal.

Keidempotensian permintaan tidak disokong. Setiap POST yang sah akan membuat tugasan berbayar yang baharu. Jika status penyerahan tidak pasti, tanya taskId yang dikembalikan; mencuba semula POST boleh membuat tugasan lain.

Pengesahan

Cipta kunci API dalam papan pemuka. Kunci lengkap hanya akan dipaparkan sekali sahaja. Simpan kunci ini pada pelayan anda dan hantarkannya sebagai token Bearer dalam setiap permintaan.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Tetapkan pemboleh ubah persekitaran SEEVIO_API_KEY sebelum menjalankan contoh ini. Contoh JavaScript dijalankan pada pelayan anda dengan Node.js; contoh Python menggunakan pakej requests.

Badan permintaan

Parameter input

Nisbah aspek ditetapkan kepada auto secara lalai. Setiap permintaan akan menjana satu imej sahaja.

Mula cepat

Hantar permintaan ringkas ini, simpan taskId yang dikembalikan, kemudian gunakan contoh pertanyaan tugasan di bawah. Nilai kredit dalam respons penciptaan ialah amaun yang ditempah.

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 cipta tugasan

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

Teks kepada imej

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

Imej kepada imej

Untuk pengeditan imej, tetapkan generation_type kepada image-to-image dan sediakan image_urls. Semua parameter lain menggunakan kontrak yang sama.

Gantikan URL media contoh.com dengan fail HTTPS anda sendiri yang boleh diakses secara awam. URL contoh disediakan hanya untuk menunjukkan struktur permintaan dan bukannya aset sampel yang boleh dimuat turun.

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

Tanya status tugasan

Gantikan ID contoh dengan taskId yang dikembalikan semasa penciptaan. Pertanyaan hanya mengembalikan tugasan milik pengguna kunci API tersebut; ID yang tidak boleh diakses atau tidak dikenali akan mengembalikan ralat HTTP 404.

Lakukan pengundian (polling) setiap 10–20 saat sebagai permulaan, kurangkan kekerapan jika menerima ralat HTTP 429, dan hentikan apabila status bertukar kepada completed atau failed. Sebaik-baiknya gunakan webhook untuk persekitaran pengeluaran. Setiap contoh kod di bawah melakukan satu pertanyaan.

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

Dalam baris gilir

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

Apabila pertanyaan mengembalikan status=failed, ini bermakna penjanaan telah tamat tetapi gagal. Rujuk failed_reason untuk mengetahui punca kegagalan dan billing_status untuk status bayaran balik. Dalam contoh ini, refunded bermakna kredit telah dikembalikan semula. credits mengekalkan amaun asal yang diketepikan, dan respons ini tidak mengandungi 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."
}

Pautan hasil disediakan selama 30 hari selepas disimpan. Selepas tamat tempoh, bahagian results akan dikosongkan.

Webhook

Tetapkan callback_url dalam permintaan cipta untuk menerima POST JSON apabila tugasan selesai atau gagal. Kembalikan respons 2xx dalam masa 15 saat. Penghantaran yang gagal akan dicuba semula; proses penghantaran berulang secara idempotensi menggunakan ID tugasan.

Pangkalan akhir (endpoint) panggilan balik anda mesti menerima permintaan POST dengan badan permintaan JSON (Content-Type: application/json).

Cipta tugasan dengan panggilan semula

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 pertanyaan tugasan; pemberitahuan kegagalan yang telah dibayar balik juga menyertakan credits_refunded pada peringkat tertinggi. Gunakan id untuk mengenal pasti tugasan dan status untuk membezakan status selesai atau gagal. Pemberitahuan mungkin berulang: proses secara idempoten mengikut id dan status. Panggilan balik tidak ditandatangani; sahkan tugasan dengan titik akhir pertanyaan yang memerlukan pengesahan identiti. Kegagalan penghantaran tidak akan mengembalikan kredit bagi tugasan yang berjaya.

Tugasan selesai: muatan panggilan balik yang berjaya

created_at ialah masa penciptaan peristiwa; task_created_at ialah masa penciptaan tugasan, dalam saat Unix. Contoh menunjukkan medan yang disyorkan; respons mungkin mengandungi medan 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
}

Tugasan gagal: muatan panggilan balik yang 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 badan panggilan balik JSON dan mengendalikan tugasan yang selesai serta gagal secara terus. Tambahkan fungsi persistensi dan penyahduplikasian ID tugasan untuk aplikasi anda; masukkan kerja yang lambat ke dalam giliran (queue) sebelum mengesahkan panggilan balik.

Ralat

Ralat HTTP mengandungi objek ralat dengan kod dan mesej. Tugasan yang berjaya diterima masih boleh gagal kemudian; tanya status tugasan atau kendalikan panggilan semula kegagalannya.

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

Ralat 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. Ralat 402 insufficient_credits bermaksud baki kredit anda tidak mencukupi untuk permintaan ini.

Had kadar

Cipta tugasan: setiap kunci API membenarkan sehingga 100 permintaan seminit secara lalai. Had kadar tersuai tidak ditawarkan buat masa ini.

Kueri tugasan: setiap kunci API membenarkan sehingga 120 permintaan seminit secara lalai. Permintaan kueri dan permintaan penciptaan tugasan dikira secara berasingan.

Permintaan penciptaan imej dan video berkongsi had kadar kunci API yang sama.

HTTP 429 menyertakan Retry-After: 60 untuk penciptaan dan Retry-After: 5 untuk pertanyaan. Gunakan fungsi undur masa (backoff) dan elakkan daripada melakukan pengundian lebih kerap daripada yang diperlukan.

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

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