Nano Banana API Kılavuzu: TokenLab Üzerinde Görsel Oluşturma ve Düzenleme

Nano Banana API'sinin TokenLab üzerinde üç ücretli model kimliği (ID) bulunur ve en ucuz olanı, orta seviyedekinin görsel başına yaklaşık yarısı kadar maliyetlidir. Pahalıya mal olan hata nadiren model seçimidir. Hata; düzenleme isteğini yanlış uç noktaya göndermek veya halihazırda bir görev oluşturmuş olan bir "create" çağrısını tekrar denemektir. Bu kılavuz; tam kimlikleri, çalışan bir metinden görsele (text-to-image) çağrısını, referans görsel çağrısını, asenkron yoklamayı (polling), beklenen hataları ve ücretlendirmenin nasıl belirlendiğini kapsar. Fiyatlar ve alan listeleri 2026-10-03 tarihinde okunmuştur, bu nedenle gönderim yapmadan önce bunları tekrar doğrulayın.

Önemli Çıkarımlar

• Tam kimliği gönderin: nano-banana-2, nano-banana-2-lite veya nano-banana-pro. Görünen adlar (display names) istek takma adları değildir.
• Nano Banana için referans görsel işlemleri, operation: "image-to-image" ve image_urls ile POST /v1/images/generations adresine gönderilir. /v1/images/edits veya /v1/chat/completions adresine gönderilmez.
• 2026-10-03 tarihinde okuduğumuz taban fiyatlar; lite, standart ve pro kimlikleri için görsel başına sırasıyla 0,0168$, 0,0335$ ve 0,067$'dır. Her modelin bir fiyat aralığı vardır, bu nedenle Kullanım (Usage) kısmından tam katmanı doğrulayın.
• task_id, status: "pending" veya poll_url içeren bir oluşturma yanıtı, completed veya failed durumuna ulaşana kadar GET /v1/tasks/{id} adresini yoklamanız (poll) gerektiği anlamına gelir.
• Bir durum okuması, görev başarısız olsa bile HTTP 200 döndürür. HTTP koduna göre değil, görevin status alanına göre dallanma yapın.
• Nihai ücretler kopyalanmış bir fiyat tablosunda değil, Kullanım (Usage) kısmında ve billing_transaction_id içinde yer alır.

Nano Banana API modelleri, fiyat birimleri ve kullanım amaçları

Bu kılavuzun önceki taslağını güncel belgelerle karşılaştırdığımızda üç sorun bulduk. Modelleri fiyatları olmadan listeliyordu. Nano Banana düzenleme işlemini chat completions üzerinden gönderiyordu. Katalogu, görsel kılavuzunun kullanmadığı bir filtreyle sorguluyordu. Aşağıdaki tablo ilk sorunu düzeltmektedir. Sonraki bölümler ise diğer ikisini düzeltir.

Model ID	En iyi kullanım alanı	Fiyatlandırma birimi	TokenLab fiyatı (USD)	Kaynak, gözlemlenen
nano-banana-2	aspect_ratio ve resolution (1k, 2k, 4k) ile metinden görsele ve görselden görsele. 2026-02-26 tarihinde yayınlandı.	per_image	İstek başına 0,0335$. Aralık 0,0225$ ile 0,0755$ arası.	Canlı model API, 2026-10-03
nano-banana-2-lite	En ucuz metinden görsele ve görselden görsele. Gördüğümüz fiyat girişi 1k katmanını kapsar.	per_image	İstek başına 0,0168$. Minimum ve maksimum değerlerin ikisi de 0,0168$.	Canlı model API, 2026-10-03
nano-banana-pro	aspect_ratio ve resolution ile metinden görsele, görselden görsele ve görsel düzenleme.	per_image	İstek başına 0,067$. Aralık 0,067$ ile 0,12$ arası.	Canlı model API, 2026-10-03
nano-banana	Sadece aspect_ratio ile metinden görsele. Halka açık resolution seçimi yok.	Verilerimizde yok	Model sayfasını veya fiyatlandırma uç noktasını kontrol edin	Katalog, 2026-10-02; Görsel Oluşturma belgeleri, 2026-10-03

Yukarıdaki tüm fiyatlar is_lock_price: true değerini taşır ve 2026-10-02T16:53:30.068Z tarihinde güncellenmiştir. Birini seçmeden önce üç detay önemlidir:

• Çözünürlük katmanları fiyatı değiştirir. Canlı API, nano-banana-2 ve nano-banana-pro için bir aralık gösterir ancak verilerimiz her katmanı bir çözünürlüğe eşlememektedir. 1k değerinin taban fiyat olduğunu varsaymayın. Modeliniz için fiyatlandırma girişlerini okuyun.
• Metin çıktısının kendi token fiyatı vardır. Hem nano-banana-2 hem de nano-banana-pro bir native-gemini-text-output girişi taşır. Bu, outputModality değeri text olduğunda geçerli olur. nano-banana-2 için 0,25 giriş ve 1,5 çıkış listeler. nano-banana-pro için 1 giriş ve 6 çıkış listeler. Birim per_token şeklindedir. Bütçenizi buna göre ayarlamadan önce GET /v1/models/:model/pricing üzerinden ölçeği doğrulayın.
• Lite, kabul edilen bir istek formatı listelemez. nano-banana-2-lite için canlı kayıt "listelenmemiş" demektedir. Üzerine geliştirme yapmadan önce detaylarını okuyun.

Kaba bir bütçe için taban fiyatı hacimle çarparız. Bunlar taban fiyat üzerinden tahminlerdir, teklif değildir:

• nano-banana-2-lite üzerinde 100 görsel: 100 × 0,0168$ = 1,68$.
• nano-banana-2 üzerinde 100 görsel: 100 × 0,0335$ = 3,35$.
• nano-banana-pro üzerinde 100 görsel: 100 × 0,067$ = 6,70$.

Daha yüksek çözünürlük katmanları bu rakamları artıracaktır.

Mevcut görsel modellerini kendiniz listelemek için görsel oluşturma kılavuzunun kullandığı uç noktayı çağırın. Önceki taslak, kılavuzun belgelemediği category=image kullanıyordu.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Bir modelin işlemleri, fiyatları ve yaşam döngüsü için Get a Model (Model Al) kısmını kullanın. Ayrıca TokenLab Modeller dizinine göz atabilirsiniz.

Nano Banana API ile metinden görsele isteği gönderin

TokenLab panosunda bir API anahtarı oluşturun ve dışa aktarın:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Her zaman model gönderin. Görsel Oluşturma referansı, görsel API'lerinin varsayılan bir model seçmediğini belirtir. Eksik bir model, param: "model" ile birlikte 400 hatası döndürür.

Bu istek, yalnızca Google görsel aileleri için belgelerde listelenen alanları kullanır. nano-banana-2 modeli 1k, 2k ve 4k değerlerini belgelediği için resolution değerini 1k olarak tuttuk.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

--max-time 120 bayrağı belgelerle uyumludur. Yüksek çözünürlüklü isteklerin bir dakika veya daha uzun sürebileceğini belirtirler, bu nedenle istemci zaman aşımınızı en az 120 saniyeye ayarlayın. Belgeler, size alanının Google görsel aileleri için bir uyumluluk takma adı olduğunu ancak doğrudan aspect_ratio kullanılmasını önerdiklerini belirtir.

Senkron bir başarı, tamamlanmış görseli satır içi olarak döndürür. Aşağıdaki yer tutucu değerler sadece belgelenmiş şekli göstermektedir:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Şu sırayla okuyun:

1. Gövdede task_id, status: "pending" veya poll_url varsa, bir görseliniz değil bir göreviniz var demektir. Yoklama (polling) bölümüne gidin.
2. Aksi takdirde data[0].url kısmını okuyun. response_format: "b64_json" ile bunun yerine data[0].b64_json kısmını okuyun.
3. created bir Unix zaman damgasıdır. revised_prompt sadece model bir tane döndürdüğünde görünür, bu yüzden zorunlu tutmayın.
4. Görsel URL'sini, kendi iş kimliğinizi (job ID), modeli ve yanıt başlıklarındaki request_id değerini saklayın.

Oluşturulan görsel URL'leri medya kopyası olarak 30 gün boyunca saklanabilir. Her öğenin durumu ve expires_at için media_retention.items kısmını kontrol edin. Bekleyen veya başarısız kopyalar garanti edilmez, bu nedenle dosyaya daha uzun süre ihtiyacınız varsa kendi depolama alanınıza kopyalayın. Veri saklama kılavuzunda detaylar mevcuttur.

Referans URL ile görsel düzenleme

Aynı ürün çekimini temiz bir stüdyo arka planında isteyen bir katalog ekibi hayal edin. Cazip olan hamle /v1/images/edits kullanmaktır. Belgeler bunu reddeder. Nano Banana referans görsel istekleri, operation: "image-to-image" ile /v1/images/generations üzerinde sunulur. /v1/images/edits onlar için doğru yol değildir.

Bu istek, model olarak nano-banana-2 ile görsel oluşturma kılavuzundan gelmektedir:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Bu şekil ile izlediğimiz kurallar:

• Tam olarak belgelenmiş referans alanlarını gönderin. JSON içinde image_url, image_urls veya reference_image_urls kullanın. Üst düzey images[] veya file_id göndermeyin. Bunlar düzenleme akışına aittir ve bu uç noktada reddedilir.
• Halka açık URL'ler kullanın. Bunlar http veya https olmalı; gömülü kimlik bilgileri, parçalar (fragments) ve özel ağ ana bilgisayarları içermemelidir. İşleme başlamadan önce süresi dolabilecek imzalı URL'lerden kaçının.
• Özel kaynaklar için multipart kullanın. Belgeler, özel veya başlık korumalı kaynaklar için multipart image dosyası sunar.
• resolution değerini modele eşleyin. Belgeler nano-banana-pro modelinin bunu içerebileceğini ve nano-banana-edit modelinin bunu atlaması gerektiğini belirtir. Belgeler ayrıca nano-banana-edit modelini bir referans görsel modeli olarak adlandırır, ancak bu kimlik 2026-10-02 tarihinde getirdiğimiz katalogda yoktur. Kullanmadan önce herhangi bir kimliği /v1/models ile doğrulayın.

Kaynak makalenin chat-completions düzenleme örneği artık yok. Canlı kayıt, nano-banana-2 ve nano-banana-pro için kabul edilen format olarak gemini_generate_content listeler. Verilerimiz bir chat-completions görsel düzenleme yolunu belgelemiyor.

Maske tabanlı boyama (inpainting) ve strength gibi parametreler verilerimizde Nano Banana için belgelenmemiştir. Bunları göndermeden önce GET /v1/models/{model} kısmını inceleyin.

Bir görsel isteği ne zaman göreve dönüşür ve nasıl yoklanır?

Bir görsel oluşturma çağrısı ya senkrondur ya da asenkrondur ve yanıt size hangisi olduğunu söyler. Asenkron işler kılavuzu tetikleyici alanları listeler: task_id, status: "pending" veya poll_url. Bunlardan herhangi biri görünürse, data[] dizisi boştur ve çalışma hala devam ediyordur.

Verilerimiz async: true istek bayrağını sadece gpt-image-2 ve resmi FLUX/BFL görsel modelleri için belgeler. Nano Banana kimlikleri için bunu belgelemez. Nano Banana isteğine bunu eklemeyin. Eğer bir görev yanıtı gelirse onu işleyin ve asenkron davranışa ihtiyacınız varsa model detaylarını kontrol edin.

Yavaş bir yanıttan sonra oluşturma çağrısını yeniden gönderen bir tarayıcı yenilemesi hayal edin. Artık iki oluşturma için ödeme yaparsınız. Belgeler, çoğu kopya oluşturmanın bu yeniden denemeden kaynaklandığını belirtir. Şu sırayı izleyin:

1. Kimlikleri hemen kaydedin. id veya task_id, poll_url, modeli, uç noktayı ve kendi iş kimliğinizi saklayın. id ve task_id aynı değerdir.
2. URL'yi yoklayın. Mevcut olduğunda poll_url kullanın. Aksi takdirde sabit rotayı çağırın:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Her 5–10 saniyede bir yoklayın. Kılavuz, bunun uzun medya işleri için genellikle yeterli olduğunu belirtir.
2. Durumları bilin. Bunlar pending, processing, completed ve failed şeklindedir. İptal edilen bir görev, cancelled: true ile birlikte failed durumunu gösterir.
3. Terminal durumunda durun. completed durumunda data[].url kısmını okuyun. Asenkron görsel sonuçları sadece URL'dir, asla b64_json değildir. failed durumunda error ve error_details kısımlarını okuyun.
4. Zaman aşımlarını güvenli bir şekilde yönetin. Bir oluşturma çağrısı yanıt almadan zaman aşımına uğrarsa, request_id değerini kontrol edin ve yeniden denemeden önce bir görev olup olmadığına bakın. Bir görev kimliği sakladıysanız, onu yoklamaya devam edin. Bir durum yoklaması başarısız olursa, o yoklamayı geri çekilme (backoff) ile yeniden deneyin ve yeniden oluşturmayın.

Bir durum okuması, başarısız bir görev için bile HTTP 200 döndürür. Başarısız görevler; status, type, code, message, param ve retryable içeren error_details içerebilir. Örneğin, param: "size" ile error_details.status: 400, isteğin düzeltilmesi gerektiği anlamına gelir. Bu, yoklamanın kendisinin başarısız olduğu anlamına gelmez. Başarısız bir oluşturmayı yeniden denemek yeni bir görev oluşturur ve yeni bir ücret oluşturabilir.

Beklenen hatalar ve yapılması gerekenler

Hataları asla message ile değil, HTTP durumu ve code ile yönetin. Hata yönetimi kılavuzu, mesajın haber verilmeksizin değişebileceğini belirtir. Chat Completions ve Responses, OpenAI tarzı bir error nesnesi kullanırken, Gemini ve Anthropic formatları kendi şekillerini korur. Tüm TokenLab API'lerinde tek bir ayrıştırıcı (parser) paylaşmayın.

Durum / kod	Muhtemel neden	Ne yapmalı
400, param: "model"	Açık model yok	model gönderin. Kimlikleri /v1/models?recommended_for=image ile listeleyin.
400 desteklenmeyen alan veya unsupported_parameter	Modelin belgelemediği bir alan, örneğin onsuz bir modelde resolution	Alanı kaldırın veya model değiştirin. Değişiklik yapmadan tekrarlamayın.
400 referans görselde	Yanlış uç nokta veya özel/süresi dolmuş URL	image_urls ile /v1/images/generations kullanın. Halka açık, kararlı bir URL kullanın.
401 invalid_api_key veya expired_api_key	Eksik, iptal edilmiş veya süresi dolmuş anahtar	Anahtarı değiştirin.
402 insufficient_balance veya quota_exceeded	Bakiye çok düşük veya anahtar kendi sınırına ulaştı	Fon ekleyin, anahtar sınırını yükseltin veya daha düşük fiyatlı bir model seçin.
403 model_not_allowed	Anahtar o modeli kullanamaz	Anahtarın model listesini güncelleyin.
404 model_not_found	Bilinmeyen veya kullanılamayan kimlik	/v1/models okuyun ve güncel bir kimlik kullanın.
413 payload_too_large	İstek veya dosya çok büyük	Girdiyi azaltın.
429 rate_limit_exceeded	Pencerede çok fazla istek	Retry-After süresini bekleyin, sonra yeniden deneyin.
500–504, all_channels_failed	Hizmet veya tedarik sorunu	Sadece retryable değeri true olduğunda yeniden deneyin. retry_after süresine uyun ve denemeleri sınırlayın.

Bir 503 all_channels_failed her zaman kesinti anlamına gelmez. Eğer retryable değeri false ise ve retry_after eksikse, işlemin seçilen Teslimat katmanında arzı yoktur. İsteği tekrarlamak yardımcı olmayacaktır, bu yüzden önce GET /v1/models kısmını kontrol edin.

Görev yoklamasının kendi hataları vardır:

• 404 async_task_not_found: görev süresi dolmuş veya gitmiş. Kaydedilen task_id ve poll_url değerlerini kontrol edin.
• 403 task_not_owned: görev başka bir çalışma alanına ait. API anahtarının hangi çalışma alanına ait olduğunu kontrol edin.
• Medya URL'si olmayan tamamlanmış bir görev: başarısız kabul edin. Kimlikleri saklayın ve destek ekibiyle iletişime geçin.

Destek ekibiyle iletişime geçtiğinizde; request_id, task_id, mevcutsa billing_transaction_id, uç nokta, model, zaman ve alan adlarını gönderin. Asla anahtarları, özel medyayı veya imzalı URL'leri göndermeyin.

Görsel isteği için ücret nasıl belirlenir?

Ücretli üç Nano Banana kimliğinin tümü per_image birimini kullanır, bu nedenle ana ücret modelin per_request fiyatıdır. Faturalandırma kılavuzu bunun etrafındaki kuralları ekler:

• Bir sonuç, bir ücret. Her tamamlanan istek, onu üreten teslimat seçeneği için bir kez ücretlendirilir. TokenLab Verified, TokenLab halka açık fiyatlarını kullanır. Official, Resmi fiyat katmanını kullanır. Auto önce Verified, sonra Official dener.
• Katmanlar nihai rakamı belirler. Canlı fiyat aralıkları (nano-banana-2 için 0,0225$ - 0,0755$, nano-banana-pro için 0,067$ - 0,12$) tek bir sabit fiyatın her isteği kapsamadığını gösterir. Çözünürlük katmanları muhtemel sürücüdür, ancak bunu modelin fiyatlandırma girişlerinde doğrulayın.
• Görevler önce rezerve eder. Asenkron bir görev, kabul edildiğinde tahmini maliyetini rezerve edebilir. Tamamlanan bir görev bir kez ücretlendirilir ve başarısız bir görev bekleyen tutarı serbest bırakır veya iade eder. Faturalandırma kılavuzu, başarısız bir görevin ücretlendirilmediğini belirtir.
• Tire işareti ücretsiz değildir. Modeller sayfasında, TokenLab fiyat sütunundaki bir tire işareti, şu anda hiçbir Verified teklifinin mevcut olmadığı anlamına gelir.

Bir ücreti doğrulamak için şu yerleri kullanın:

1. Güncel fiyat için GET /v1/models/:model/pricing veya Fiyatlandırma API'si.
2. Ücretli oluşturmayı onaylamadan önce maksimum tahmini gösteren Konsol.
3. Modele göre nihai ücret için Kullanım (Usage).
4. Yanıt veya görevdeki billing_transaction_id ve X-Billing-Transaction-ID başlığı. Akış (streaming) ve bazı yerel formatlar bunu sadece başlıkta gösterebilir.

Kullanım (Usage) kısmı, bir görev bittikten sonra nihai ücreti veya serbest bırakılan tutarı göstermiyorsa, İstek Kimliğini ve görev kimliğini support@tokenlab.sh adresine gönderin. Bu makaledeki fiyatları kodunuza kopyalamayın. Faturalandırma kılavuzu, uygulamanız maliyetleri görüntülemesi veya karşılaştırması gerektiğinde güncel fiyatı okumanızı söyler.

SSS

Görselden görsele (image-to-image) istekleri için hangi Nano Banana model kimliğini göndermeliyim?

Canlı kayıtlar nano-banana-2, nano-banana-2-lite ve nano-banana-pro için image-to-image listeler. Belgeler ayrıca nano-banana-edit modelini de adlandırır, ancak bu 2026-10-02 tarihinde getirdiğimiz katalogda yoktur. operation: "image-to-image" ve image_urls ile /v1/images/generations adresine kimliği gönderin. Kendi görselleriniz üzerinde küçük bir test çalıştırın, çünkü verilerimizde kalite karşılaştırması yoktur.

Görsel isteğim neden görsel yerine task_id döndürdü?

Oluşturma çağrısı asenkron bir görev olarak çalıştı. Yanıtta task_id, status: "pending" veya poll_url arayın. Bu alanları kaydedin, ardından durum completed veya failed olana kadar her 5–10 saniyede bir poll_url veya GET /v1/tasks/{id} adresini yoklayın. Siz beklerken ikinci bir oluşturma isteği göndermeyin.

Bir Nano Banana modelinden base64 çıktısı alabilir miyim?

response_format alanı url veya b64_json değerlerini kabul eder ve senkron bir istek data[].b64_json döndürebilir. Asenkron görsel sonuçları, hangi formatı isterseniz isteyin sadece URL'dir. Seçilen modelin b64_json kabul ettiğini doğrulamak için detaylarını kontrol edin, çünkü alanlar modele göre farklılık gösterir.

Başarısız bir görsel görevi ücretlendirilir mi?

Faturalandırma kılavuzu, başarısız bir görevin ücretlendirilmediğini ve bekleyen tüm rezervasyonların serbest bırakıldığını veya iade edildiğini belirtir. Başarısız bir oluşturmayı yeniden denemek yeni bir görev oluşturur ve yeni bir ücret oluşturabilir. billing_transaction_id ve task_id kullanarak Kullanım (Usage) kısmından sonucu doğrulayın.

TokenLab panosunda bir anahtar oluşturun, yukarıdaki metinden görsele isteğini nano-banana-2-lite ile gönderin ve Kullanım (Usage) kısmından ücreti kontrol edin.