Gemini görsel API'sini proxy ile kullanma

Gemini görsel API proxy hizmeti, uygulamanız ile Gemini görsel modeli arasında çalışan bir API ağ geçididir. Bağlantı için görsel üreten bir model kimliği, hizmetin istek biçimi ve gerçek görseli alma yöntemi gerekir. Metin istemcisinin temel URL'sini değiştirmek, görsel oluşturmanın desteklendiğini göstermez.

OmniaKey belgelerindeki akış görev oluştur → durumunu sorgula → sonucu indir şeklindedir ve POST /v1/media/tasks ile başlar. Bu rehber akışı tamamlar; Google'ın yerel API'si ve OpenAI uyumlu arayüzlerle farklarını açıklar.

Hangi proxy türüne ihtiyacınız var?

Burada kastedilen; model isteklerini, kimlik doğrulamayı ve yanıtları işleyen uygulama düzeyinde bir API hizmetidir. Ağ proxy'si trafiği iletir, ancak tek başına bir görsel API biçimini diğerine dönüştürmez. Seçiminizi hizmetin yayımladığı teknik sözleşmeye göre yapın.

Google'ın güncel görsel oluşturma rehberi Interactions API örneklerini kullanır. GenerateContent başvurusu ayrı bir sözleşme tanımlar. İstek alanlarını veya yanıt ayrıştırıcılarını karıştırmayın; proxy'nin her ikisini sunduğunu varsaymayın.

Görsel anlama ile görsel oluşturma da farklıdır. Bir model fotoğrafı açıklayabilir fakat yalnızca metin döndürebilir. Başarılı bir metin çağrısı görsel üretimini veya düzenlemeyi doğrulamaz. “OpenAI uyumlu” ifadesi de bir görsel yolunda tüm SDK yöntemlerinin desteklendiğini kanıtlamaz.

Belirli bir görsel modeli seçin

Google'ın model rehberi şu kimlikleri ayırır:

• Nano Banana 2.1: gemini-nano-banana-2.1; Google'ın yeni genel görsel iş akışları için önerdiği başlangıç noktası.
• Nano Banana Pro: gemini-3-pro-image; daha zorlu görsel görevler için ayrı bir seçenek.
• Nano Banana 2: gemini-3.1-flash-image; önceki nesil, 2.1'in başka adı değil.

Kimliği çağrı yapacağınız hizmetten kopyalayın. Yetkileri, oluşturma ve düzenleme desteğini, boyutu ve ücret birimini kontrol edin. OmniaKey, 2.1 için parameters.aspect_ratio ve parameters.image_size alanlarını, 1K, 2K, 4K çıktı seçeneklerini belgeler. Bunlar Google'ın imageConfig alanıyla veya GPT Image'ın size ve quality alanlarıyla doğrudan değiştirilemez.

Güncel hizmet bilgisi için Nano Banana 2.1 model sayfasına, model seçimi için 2.1 ve Pro karşılaştırmasına bakın.

OmniaKey ile bir görsel oluşturun

Bash, cURL, jq ve yerel OMNIAKEY_API_KEY ortam değişkeninde saklanan bir OmniaKey anahtarı gerekir. Komutları sunucuda veya geliştirme bilgisayarınızda çalıştırın; anahtarı tarayıcı koduna koymayın. Basit İngilizce örnek istem, kaliteyi değerlendirmeden önce API akışını doğrulamak içindir.

1. Görevi oluşturup kaydedin

Bu mantıksal görsel isteği için benzersiz bir Idempotency-Key seçin. Örnekteki değer gösterim amaçlıdır: yeni bir görevde değiştirin, aynı görevi tekrarlarken anahtarı ve gövdeyi aynen koruyun. Göndermeden önce ikisini de uygulamanızda kaydedin.

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

Yalnızca cURL başarılıysa ve task.json içinde bir id varsa devam edin. Yeni görev 202 Accepted döndürür; aynı anahtar ve gövdeyi yinelemek, ilk görevi 200 ile getirir. Kabul edilmesi görselin tamamlandığı anlamına gelmez. Ayrıntılar için görev yaşam döngüsüne bakın.

2. Kaydedilen kimliği sorgulayın

Bu Bash örneği sorgu sayısını sınırlar. Sınıra gelindiğinde aynı kimlikle daha sonra devam edebilirsiniz. Görevi iptal etmez veya yeniden oluşturmaz.

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

Oluşturma isteği kimlik dönmeden zaman aşımına uğrarsa aynı gövde ve aynı idempotency anahtarıyla tekrar gönderin. Kimlik varsa o görevi sorgulayın. Yeni anahtar ikinci bir ücretli görev oluşturabilir. Kurtarma, saklama süresine bağlıdır: görev kayıtları oluşturulduktan sonra 24 saat tutulur.

3. Yalnızca başarılı sonucu indirin

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

Dosya uzantısını seçmek için mime_type alanını okuyun; dosyanın açıldığını ve beklenen boyutlarda olduğunu doğrulayın. İmzalı URL'lerin süresi dolar. Görev ve dosya hâlâ mevcutken yeniden sorgulayarak yeni bağlantı alabilirsiniz. Saklayacağınız sonuçları indirin; imzalı bağlantı kalıcı depolama değildir.

Referans görselle düzenleme yapın

operation: "edit" kullanın ve input.image içinde satır içi Base64 verisi gönderin. Desteklenen çoklu referanslar için input.images kullanılır. Düzenleme talimatını input.prompt içinde tutun. Tam istek biçimi görsel API belgelerinde yer alır.

Görev API'sinde Base64 dâhil tüm istek gövdesi 1 MiB ile sınırlıdır. Gerekirse referansı sıkıştırın veya küçültün. Google'ın doğrudan yükleme sınırı, proxy'nin sınırının yerine geçmez. Küçük bir referans ve açık bir değişiklikle başlayın; korunması gereken ayrıntıları da inceleyin.

İstemi, referansı, modeli veya parametreyi değiştirmek yeni bir istektir ve yeni anahtar gerektirir. Aynı anahtarın farklı gövdeyle kullanılması 409 idempotency_key_reused döndürür.

Hatanın hangi katmanda olduğunu bulun

Google'ın sorun giderme rehberi Google'ın davranışını açıklar. Proxy ek bir katmandır. HTTP durumunu, hata kodunu, görev kimliğini ve süreyi hassas verileri çıkartarak kaydedin. Anahtarları ve özel referans görsellerini günlüklere koymayın. 200 dönen JSON tek başına kullanılabilir görsel kanıtı değildir.

Maliyeti karşılaştırın ve bağlantıyı doğrulayın

Google'ın doğrudan fiyatı ve proxy fiyatı farklı tekliflerdir. Toplu çalışmadan önce güncel OmniaKey fiyatlarını ve modelin ücret birimini kontrol edin. Görsel çıktıya metin token fiyatı uygulamayın; bireysel Gemini aboneliğinin proxy çağrılarını ödediğini varsaymayın.

Kullanışlı ölçü toplam tahsil edilen tutar ÷ kabul edilen görsel sayısıdır. Ücretli tekrarları ve incelemede elenen çıktıları da ekleyin. Bu bir planlama formülüdür; ölçülmüş performans sonucu veya en düşük fiyat vaadi değildir.

Hacmi artırmadan önce beş küçük senaryoyu deneyin:

1. Metin istemi, açılabilen ve beklenen biçim ile boyutta bir görsel döndürür.
2. Referans düzenleme, istenen değişikliği yapar ve gerekli ayrıntıları korur.
3. Aynı anahtar ve gövde yeniden gönderildiğinde aynı görev kimliği gelir.
4. Yerel zaman aşımından sonra yeni görev oluşturmadan aynı kimlikle devam edilir.
5. Geçersiz parametre veya kullanılamayan model, sahte başarı yerine anlaşılır hata verir.

Modeli, parametreleri, süreyi, son durumu, ücreti ve inceleme sonucunu kaydedin. Gerçek iş materyallerini göndermeden önce istemlerin ve referansların nasıl işlendiğini kontrol edin.

Sık sorulan sorular

Mevcut SDK'da yalnızca temel URL'yi değiştirebilir miyim?

Yalnızca proxy, SDK'nın beklediği uç noktayı, alanları ve görsel yanıtını belgeliyorsa. Görsel işlemini ayrıca deneyin; çalışan sohbet isteği yeterli değildir.

Proxy Gemini sınırlarını kaldırır mı?

Hayır. Sağlayıcı, model, proxy ve hesap sınırları birlikte uygulanabilir. Ağ geçidi sınırsız görsel veya bölgesel kullanılabilirlik garantisi vermez.

Hangi modelle başlamalıyım?

Güncel kataloğu kontrol edip desteklenen bir modeli küçük görevle değerlendirin. Nano Banana 2.1 rehberi model değişikliklerini açıklar; bu yazı API bağlantısına ve doğrulamaya odaklanır.

Kaynaklar ve sonraki adım

Temel kaynaklar Google'ın görsel rehberi, GenerateContent başvurusu, sorun giderme rehberi ve bağlantı verilen OmniaKey belgeleridir. Google kaynakları İngilizcedir. Sözleşmeler 14 Ekim 2026 tarihinde doğrulandı; örneği çalıştırmadan önce model erişimini kontrol edin.