# Gemini görsel API proxy ile bağlantı ve hata çözümü

> Gemini görsel API'sini proxy üzerinden bağlayın: model ve istek biçimi, görev oluşturma, sonucu indirme, güvenli tekrarlar ve kullanılabilir görsel maliyeti.

- Canonical HTML: https://omniakey.com/tr/blog/gemini-image-api-relay
- Markdown: https://omniakey.com/tr/blog/gemini-image-api-relay.md
- Published: 2026-10-14 (updated 2026-10-14)
- Author: Kiki, COO at OmniaKey
- Language: tr
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

**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 görsel akışı, 14 Ekim 2026'da kontrol edildiği haliyle **görev oluştur → durumunu sorgula → sonucu indir** şeklindedir ve `POST /v1/media/tasks` ile başlar. Aşağıda akışın tamamı ve Google'ın yerel API'si ile OpenAI uyumlu arayüzlerden farkları anlatılır.

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

|Arayüz|İstek biçimi|Görsel nereden alınır?|
|-|-|-|
|Gemini GenerateContent|`/v1beta/models/MODEL:generateContent`; `contents` ve desteklenen `generationConfig` alanları|`candidates[].content.parts[].inlineData` gibi görsel parçaları|
|OpenAI uyumlu proxy|Sağlayıcının belgelediği uç nokta ve görsel şeması|Sağlayıcının yanıt biçimindeki görsel verileri veya URL'ler|
|OmniaKey görsel görevleri|`/v1/media/tasks`; `model`, `type`, `operation`, `input`, `parameters`|Önce görev kimliği, `succeeded` sonrasında `assets[]`|

Google'ın güncel [görsel oluşturma rehberi](https://ai.google.dev/gemini-api/docs/image-generation) **Interactions API** örneklerini kullanır. [GenerateContent başvurusu](https://ai.google.dev/api/generate-content) 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](https://ai.google.dev/gemini-api/docs/image-generation) ş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](https://omniakey.com/tr/gemini-nano-banana-2-1), model seçimi için [2.1 ve Pro karşılaştırmasına](https://omniakey.com/tr/blog/nano-banana-2-1-vs-pro) bakın. Relay çağrısını yazmadan önce Nano Banana 2.1'i ve diğer Nano Banana modellerini denemek için [AI Görsel Üretici](https://omniakey.com/tr/ai-image-generator)'yi açı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.

```bash
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. `202` yanıtı görselin tamamlandığı anlamına gelmez. Ayrıntılar için [görev yaşam döngüsüne](https://docs.omniakey.com/tr/media/overview) 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.

```bash
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

```bash
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](https://docs.omniakey.com/tr/media/image) 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

|Belirti|Kontrol|Sonraki adım|
|-|-|-|
|`401` / `403`|Anahtar, sunucu adresi, kimlik doğrulama, model yetkisi|Önce kimlik bilgilerini veya izinleri düzeltin|
|`400` / `404`|Uç nokta, model kimliği, alanlar, görev sahibi|Sözleşmeyi inceleyin; model takma adı tahmin etmeyin|
|`413`|Base64 dâhil toplam gövde|Girdi görselini küçültün|
|`409 idempotency_key_reused`|Aynı anahtarın farklı gövdeyle kullanılması|Kurtarma için ilk gövdeyi, yeni görev için yeni anahtarı kullanın|
|`429`|Kota, istek sıklığı, eşzamanlılık|Hatayı okuyun, yükü azaltın ve uygunsa sınırlı artan bekleme uygulayın|
|`503`|Yapılandırma mı geçici kapasite sorunu mu?|`worker_disabled` ve `no_available_channel` için yapılandırma ve kullanılabilirliği kontrol edin|
|Yalnızca metin veya boş çıktı|Görsel çıktısı, güvenlik geri bildirimi, ayrıştırıcı|GenerateContent için `promptFeedback`, `finishReason` ve tüm parçaları inceleyin|
|Sorgulama zaman aşımı|Görev hâlâ çalışıyor mu?|Aynı kimlikle devam edin, yerel bekleme bitti diye yeniden oluşturmayın|

[Google'ın sorun giderme rehberi](https://ai.google.dev/gemini-api/docs/troubleshooting) Google'ın davranışını açıklar. Gemini görsel API 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ı](https://omniakey.com/tr/pricing) 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](https://omniakey.com/tr/models) kontrol edip desteklenen bir modeli küçük görevle değerlendirin. [Nano Banana 2.1 rehberi](https://omniakey.com/tr/blog/nano-banana-2-1-review) 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](https://ai.google.dev/gemini-api/docs/image-generation), [GenerateContent başvurusu](https://ai.google.dev/api/generate-content), [sorun giderme rehberi](https://ai.google.dev/gemini-api/docs/troubleshooting) ve bağlantı verilen OmniaKey belgeleridir. Google kaynakları İngilizcedir. Sözleşmeler **14 Ekim 2026** tarihinde doğrulandı; örneği çalıştırmadan önce [Nano Banana 2.1 model sayfasından](https://omniakey.com/tr/gemini-nano-banana-2-1) model erişimini kontrol edin.
