Nano Banana 2.1 API

Yetenekler

Fiyatlandırma ve krediler

Her istek bir görsel oluşturur. Kredi miktarı aşağıdaki çözünürlüğe bağlıdır. Krediler kabul sırasında ayrılır, başarıda tahsil edilir ve hata durumunda iade edilir.

İsteklerde aynı işlemin tekrar ücretlendirilmesini önleyen idempotency desteği yoktur. Her geçerli POST isteği, ücretlendirilebilir yeni bir görev oluşturur. Gönderim sonucunun belirsiz olduğu durumlarda, dönen taskId değerini sorgulayın; POST isteğinin yeniden denenmesi başka bir görev oluşturabilir.

Kimlik doğrulama

Panelde bir API anahtarı oluşturun. Anahtarın tamamı yalnızca bir kez gösterilir. Bu anahtarı sunucunuzda saklayın ve her istekte Bearer token olarak gönderin.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Bu örnekleri çalıştırmadan önce SEEVIO_API_KEY ortam değişkenini tanımlayın. JavaScript örnekleri sunucunuzda Node.js ile çalışır; Python örnekleri ise requests paketini kullanır.

İstek gövdesi

Giriş parametreleri

En boy oranı varsayılan olarak auto (otomatik) ayarlanır. Her istek tam olarak bir görsel oluşturur.

Hızlı başlangıç

Bu temel isteği gönderin, dönen taskId değerini kaydedin ve ardından aşağıdaki görev sorgulama örneğini kullanın. İstek oluşturma yanıtındaki credits değeri, ayrılan (rezerve edilen) miktarı gösterir.

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

Görev oluşturma yanıtı örneği

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

Metinden görsele

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

Görselden görsele

Görsel düzenleme için generation_type parametresini image-to-image olarak ayarlayın ve image_urls değerlerini sağlayın. Diğer tüm parametreler aynı kurallara tabidir.

example.com medya URL'lerini kendi genel erişime açık HTTPS dosyalarınızla değiştirin. Örnek URL'ler istek yapısını göstermek amaçlıdır ve indirilebilir örnek varlıklar değildir.

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

Görev sorgula

Örnek kimliği, oluşturma sırasında dönen taskId ile değiştirin. Sorgular yalnızca API anahtarının sahibine ait görevleri döndürür; erişilemeyen veya bilinmeyen kimlikler HTTP 404 döndürür.

Başlangıçta her 10-20 saniyede bir sorgulama yapın, HTTP 429 hatasında sıklığı azaltın ve durum completed veya failed olduğunda sorgulamayı durdurun. Üretim ortamında webhook'ları tercih edin. Aşağıdaki her kod örneği tek bir sorgu gerçekleştirir.

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

Sırada

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

Tamamlandı

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

Başarısız

Sorgu status=failed değerini döndürdüğünde üretim süreci başarısızlıkla sonuçlanmış demektir. Hatanın nedenini öğrenmek için failed_reason alanını, iade sonucunu görmek için ise billing_status alanını inceleyebilirsiniz. Bu örnekteki refunded ifadesi, kredilerin iade edildiğini gösterir. credits alanı orijinal rezerve edilen miktarı korur ve yanıt data alanını içermez.

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

Sonuç bağlantıları, depolamadan sonraki 30 gün boyunca kullanılabilir. Süre dolduktan sonra results alanı boş döner.

Webhook'lar

Görev tamamlandığında veya başarısız olduğunda bir JSON POST isteği almak için oluşturma isteğinde callback_url alanını ayarlayın. 15 saniye içinde bir 2xx yanıtı döndürün. İletilemeyen bildirimler tekrar denenir; yinelenen bildirimleri görev kimliğine göre tekilleştirerek (idempotent) işleyin.

Geri arama (callback) uç noktanız, JSON istek gövdesine (Content-Type: application/json) sahip POST isteklerini kabul etmelidir.

Geri çağırma (callback) ile görev oluşturma

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

Geri çağırmalar (callbacks) görev sorgulama yanıt yapısını kullanır; iadeyle sonuçlanan başarısızlık bildirimleri ayrıca üst düzeyde credits_refunded bilgisini içerir. Görevi tanımlamak için id, tamamlananları başarısız olanlardan ayırt etmek için ise status değerini kullanın. Bildirimler tekrarlanabilir: Bunları id ve status değerlerine göre mükerrerliği önleyecek şekilde (idempotent) işleyin. Geri çağırmalar imzasızdır; görevi doğrulamak için kimliği doğrulanmış sorgu uç noktasını kullanın. Gönderim hatası, başarıyla tamamlanan bir görevin ücret iadesini tetiklemez.

Görev tamamlandı: Başarılı geri arama yükü

created_at olayın, task_created_at görevin oluşturulma zamanıdır; ikisi de Unix saniyesidir. Örnekler önerilen alanları gösterir; yanıtlar ek alanlar içerebilir.

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

Görev başarısız oldu: Başarısızlık geri arama yükü

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

Alıcı örneği

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

Bu Next.js örneği, JSON geri arama gövdesini okur ve tamamlanan ya da başarısız olan görevleri doğrudan işler. Kendi uygulamanız için veri kalıcılığı ve görev kimliği (task-ID) tekilleştirme özellikleri ekleyin; geri aramayı onaylamadan önce yavaş çalışan işlemleri sıraya alın.

Hatalar

HTTP hataları, code ve message içeren bir error nesnesine sahiptir. Başarıyla kabul edilen bir görev daha sonra yine de başarısız olabilir; görevi sorgulayın veya başarısızlık geri çağırmasını işleyin.

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

Hatalar error.code ve error.message kullanır: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. 402 insufficient_credits hatası, mevcut kredilerinizin bu istek için yetersiz olduğu anlamına gelir.

İstek sınırları

Görev oluşturma: Her bir API anahtarı, varsayılan olarak dakikada en fazla 100 isteğe izin verir. Özel istek limitleri şu anda desteklenmemektedir.

Görev sorgulama: Her bir API anahtarı, varsayılan olarak dakikada en fazla 120 isteğe izin verir. Sorgulama istekleri ve görev oluşturma istekleri birbirinden bağımsız olarak sayılır.

Görsel ve video oluşturma istekleri aynı API anahtarı istek sınırını (rate limit) paylaşır.

HTTP 429 hatası, oluşturma için Retry-After: 60 ve sorgular için Retry-After: 5 başlıklarını içerir. Geri çekilme (backoff) yöntemini kullanın ve gereğinden daha sık sorgulama yapmaktan kaçının.

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

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