Nano Banana API

Yetenekler

Fiyatlandırma ve krediler

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.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

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

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

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

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

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

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

Görselden görsele

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

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

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",
  "credits": 2,
  "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",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

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",
  "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 use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

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",
  "credits": 2,
  "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",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 2
}

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

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

İ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.

Image and video creation requests share the same API key rate limit.

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