Gemini 3.8 Flash API Nasıl Kullanılır: Etkileşim API'si, Düşünce Seviyeleri ve Apidog'da İlk Çağrınız

Google, Gemini 3.8 Flash'ı 2 Eylül 2026'da yayınladı ve API model kimliği, önizleme eki olmayan `gemini-3.8-flash` düz dizesidir. 31 Aralık 2026'ya kadar 3.7 Flash'ın milyon giriş jetonu başına 0,75 dolar ve milyon çıkış jetonu başına 3,75 dolarlık tanıtım fiyatını koruyor ve Google bunu "daha çok çalışan" bir model olarak tanımlıyor: karmaşık görevlerde daha fazla muhakeme adımı atıyor ve araçları daha sık çağırıyor, bu da jeton faturanızda görünüyor.

Bu kılavuz, çalışan bir entegrasyona giden tüm yolu kapsar: AI Studio'da bir anahtar edinme, Interactions API (şimdi Google'ın Gemini 3.x için birincil API'si) aracılığıyla ilk isteği gönderme, mevcut kodun çoğu tarafından hala kullanılan eski `generateContent` eşdeğeri, her birinde `thinking_level`'ın nereye gittiği, akış ve düşünme maliyetinin sizi asla şaşırtmaması için `thoughtsTokenCount`'ı nasıl okuyacağınız. Her çağrı, düz JSON ile HTTP'dir, bu nedenle uygulama koduna girmeden önce her birini Apidog'da oluşturabilir ve kontrol edebilirsiniz.

Model genel görünümü, kıyaslamalar ve neyin değiştiği için, Gemini 3.8 Flash nedir ile başlayın. Google'ın lansman yazısı resmi çerçeveyi sunar.

Gemini 3.8 Flash API'ye hızlı bir bakış

Kod yazmadan önce iki ayrıntı öne çıkıyor. Varsayılan düşünme seviyesi Gemini 3 Pro'daki gibi `high` değil, `medium`'dur. Ve düşünme jetonları resmi fiyatlandırma sayfasında çıkış oranı üzerinden faturalandırılır, bu nedenle seçtiğiniz seviye, kalite kadar bir maliyet kararıdır. Fiyatlandırma dökümü görev başına sayıları açıklar.

Adım 1: AI Studio'da bir API anahtarı alın

Google AI Studio'yu açın, bir Google hesabıyla oturum açın ve anahtar sayfasından bir API anahtarı oluşturun. Anahtar, hız sınırları ve Google'ın ücretsiz katman verilerinin "ürünlerimizi geliştirmek için kullanıldığını" belirtmesiyle birlikte hemen ücretsiz katmanda çalışır. Üretim limitleri için 1. Katmana geçmek için bir faturalandırma hesabı bağlayın.

Anahtarı koda yapıştırmak yerine dışa aktarın:

export GEMINI_API_KEY="AIza..."

Resmi Python SDK'sı `GEMINI_API_KEY`'i ortamdan okur, bu nedenle `genai.Client()`'ın hiçbir argümana ihtiyacı yoktur. `pip install google-genai` ile yükleyin.

Adım 2: Interactions API ile ilk çağrınız

Google artık Interactions API'yi Gemini 3.x modellerini çağırmanın birincil yolu olarak kabul ediyor. İstek tek bir JSON nesnesidir: model, bir `input` ve `thinking_level`'ın bulunduğu isteğe bağlı bir `generation_config`.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "HTTP önbelleklemesini 3 cümlede açıklayın.",
    "generation_config": {"thinking_level": "medium"}
  }'

Yanıt, tek bir mesaj yerine bir dizi yürütme adımıdır. Model düşünceleri ve araç çağrıları adım olarak görünür ve son adım, metni içeren `model_output`'tur. Python'da SDK bunu sizin için düzleştirir:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="HTTP önbelleklemesini 3 cümlede açıklayın.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

`temperature`, `top_p` ve `top_k`'yi dışarıda bırakın. Google'ın her Gemini 3 modeli için önerisi, `temperature`'ı varsayılan değeri olan 1.0'da tutmaktır, çünkü düşürmek "döngüye veya performans düşüşüne neden olabilir". Eğer eski bir modelden bir yapılandırma kopyaladıysanız, silinecek ilk satır budur.

Adım 3: `previous_interaction_id` ile çoklu dönüş

Interactions API, varsayılan olarak sunucuda konuşma durumunu korur. Bir konuşmayı sürdürmek için, önceki yanıtın `id`'sini yalnızca yeni kullanıcı girişiyle birlikte `previous_interaction_id` olarak gönderin. Geçmişi yeniden göndermezsiniz.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Şimdi bir Cache-Control başlığı örneği verin.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

Uyumluluk kurallarınız sunucu tarafı depolamayı yasaklıyorsa, `store: false` olarak ayarlayın. Bunun dezavantajı, o zaman durumu kendinizin yönetmesi, modelin düşünce bloklarını ve düşünce imzalarını her dönüşte tam olarak aldığınız gibi geri göndermek de dahil olmak üzere. Bu, 3.8 Flash için fonksiyon çağırma kılavuzunda ele alınan, araç kullanımını zorlaştıran aynı kuraldır.

Adım 4: Eski `generateContent` yolu

Üretimdeki çoğu Gemini kodu hala `generateContent`'i çağırıyor. Google bunu eski olarak adlandırıyor, ancak herhangi bir sona erme tarihi olmadan "tamamen desteklenmeye devam ediyor", bu yüzden bugün hiçbir şeyi yeniden yazmanız gerekmiyor. Gemini 3.7 Flash API kılavuzumuz yalnızca bu yolu ele aldı; 3.8 Flash için şekil aynıdır ve düşünme ayarı Interactions'dakinden farklı bir yerdedir.

`generateContent`'te, seviye `generationConfig.thinkingConfig.thinkingLevel` altında, camelCase ile yer alır:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "HTTP önbelleklemesini 3 cümlede açıklayın."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

Python karşılığı, türlendirilmiş yapılandırma nesnelerini kullanır:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="HTTP önbelleklemesini 3 cümlede açıklayın.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

Eğer bir tam sayı olarak `thinking_budget` kullanan bir yapılandırmadan geliyorsanız, onu dize enum'u ile değiştirin. `candidate_count` da Gemini 3 ve sonrasında kaldırılmıştır. Her değişiklik için önceki ve sonraki JSON ile tam kontrol listesi, 3.7'den 3.8 Flash'a geçiş kılavuzunda yer almaktadır.

İki API arasında yeniden okumaya gerek kalmadan çeviri yapabilmeniz için aynı endişeler yan yana verilmiştir:

Adım 5: Akış ve düşünme maliyetini okuma

Sohbet arayüzleri için, sunucu tarafından gönderilen olayları (her olay için tek bir kısmi `candidates` bloğu) almak üzere yöntem adını `streamGenerateContent` ile değiştirin ve `?alt=sse` ekleyin:

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Üç HTTP önbellekleme başlığını listeleyin."}]}]}'

Akışlı olsun veya olmasın, her `generateContent` yanıtı bir `usageMetadata` nesnesiyle biter. Bunu her çağrıda okuyun:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

`thoughtsTokenCount`, 3.8 Flash'ta dikkat edilmesi gereken sayıdır. Düşünme jetonları, tanıtım döneminde milyon başına 3,75 dolardan çıkış jetonları olarak faturalandırılır ve Google, modelin "performansı en üst düzeye çıkarmak için, özellikle daha yüksek çaba seviyelerinde daha fazla jeton kullanabileceğini" belirtir. Artificial Analysis, `high` seviyesindeki endeks çalışmasında görev başına yaklaşık 48 bin çıkış jetonu ölçtü, bu 3.7 Flash'tan %30 daha fazla, jeton başına fiyatlar değişmemesine rağmen görev başına maliyeti 0,40 dolardan 0,58 dolara yükseltti. `medium` ve `low` seviyelerindeki çalışmaları görev başına 0,41 ve 0,24 dolar olarak gerçekleşti. Düşünme seviyeleri kılavuzu bu sayıları yol başına bir stratejiye dönüştürüyor.

Modelin ne hakkında muhakeme yaptığını görmek için `thinkingConfig` içine `"includeThoughts": true` ekleyin. Düşünce özetleri, `"thought": true` ile işaretlenmiş parçalar olarak geri gelir; görünür yanıtı oluştururken bunları atlayın.

İlk saatte karşılaşacağınız hatalar

`thinking_level: "minimal"` doğrulama hatası verir. Gemini 3.8 Flash yalnızca `low`, `medium` ve `high` seviyelerini destekler. `minimal` göndermek "Bu model için MINIMAL düşünme seviyesi desteklenmiyor. Lütfen başka bir düşünme seviyesiyle tekrar deneyin." mesajıyla birlikte bir `400 INVALID_ARGUMENT` döndürür (3 Eylül 2026'da canlı bir çağrı ile doğrulandı) ve düzeltme `low` olarak tek kelimelik bir değişikliktir. Eski 3.x yapılandırmaları ve kopyalanan kod parçacıkları genellikle bunun kaynağıdır.

429, hata değil, katmanınızın limitine ulaştığınız anlamına gelir. Hız limitleri sayfası katmanları açıklar: ücretsiz katman hız sınırlıdır, 1. Katman faturalandırma hesabı bağladığınızda açılır, 2. Katman 100 $ harcama ve üç gün gerektirir ve 3. Katman 1.000 $ ve 30 gün gerektirir. Model başına dakika başına istek ve dakika başına jeton sayıları yalnızca AI Studio hız limiti sayfasında hesabınız için gösterilir, bu nedenle bir blog yazısından bir sayıya güvenmek yerine orayı kontrol edin. Bir 429'da, geri çekilin ve tekrar deneyin; düşük hacimli tekrarlanan 429'larda, katmanı yükseltin. Çevrimdışı işler için, Batch API daha iyi bir çözümdür: %50 indirimle çalışır (tanıtım döneminde milyon jeton başına 0,375 $ / 1,875 $) ve 1. Katmanda 3 milyon, 2. Katmanda 400 milyon ve 3. Katmanda 1 milyar kendi kuyruklu jeton limitlerine sahiptir. Gemini toplu mod kılavuzu istek şeklini gösterir.

Bir fonksiyon sonucunda `call_id` eksik. Eğer araçları kullanıyorsanız, her `function_result` (Interactions) 3.8 Flash'ta hem `call_id` hem de `name` taşımalıdır ve her eski `functionResponse` eşleşen `id` artı `name` taşımalıdır. Bunlardan herhangi birini atlamak, dönüşü başarısız kılar.

Her iki uç noktayı da Apidog'da yayınlanmadan önce test edin

Her iki istek de terminalden çalıştığında, bunları tüm ekibin çalıştırabileceği bir yere taşıyın. Apidog'u indirin, bir proje oluşturun ve yukarıdaki iki uç noktayı kaydedilmiş istekler olarak ekleyin. Dört alışkanlık karşılığını verir:

• Anahtarı isteğin dışında tutun. `GEMINI_API_KEY`'i bir ortam değişkeni olarak ekleyin ve `x-goog-api-key` başlığında `{{GEMINI_API_KEY}}` olarak referans gösterin. Kaydedilmiş istek asla sırrı içermez ve ücretsiz katman anahtarı ile faturalandırılmış anahtar arasında geçiş yapmak tek bir ortam değişikliğidir.
• Durum ve jeton kullanımı üzerinde iddia ekleyin. Durumun 200 olduğuna dair bir iddia ekleyin, ardından `usageMetadata.thoughtsTokenCount`'ın her istem için seçtiğiniz bir tavanın altında kaldığına dair bir JSON yol iddiası ekleyin. Tavan, maliyet regresyonu alarmınızdır: bir istem güncellemesi veya sessiz bir model değişikliği düşünme jetonlarını artırırsa, fatura gelmeden önce test başarısız olur. SSE test kılavuzu, Apidog'un ham parçalar yerine birleştirilmiş bir olay akışı olarak işlediği akış varyantını kapsar.
• Aynı istemi üç seviyede de gönderin. İsteği `low`, `medium` ve `high` ile çoğaltın ve `thoughtsTokenCount` ile yanıt süresini yan yana karşılaştırın. Bu, istemleriniz için dizin ortalamaları yerine gerçek sayılar verir.
• Planlayın. İstekleri bir test senaryosuna dönüştürün ve bir programa göre çalıştırın, böylece bir hız limiti değişikliği, `minimal` kaldırma gibi bir doğrulama değişikliği veya bir jeton artışı üretimde değil, bir raporda görünür. Apidog'da API testleri nasıl planlanır kurulumu açıklar.

Apidog modeli çalıştırmaz veya SDK'yı değiştirmez. Size, çoğu ekibin bir şeyler bozulana kadar atladığı kısım olan HTTP çağrılarının kaydedilmiş, paylaşılabilir, iddia edilebilir bir sürümünü verir.

SSS

Yeni projeler hangi uç noktayı kullanmalı? Interactions API. Google, `generateContent`'i eski olarak adlandırıyor ve hala tamamen destekleniyor, ancak yeni özellikler önce Interactions'a gelir ve sunucu tarafı durum çoklu dönüş kodunu daha kısa yapar. Geçiş yapmak için bir nedeniniz olana kadar mevcut hizmetler için `generateContent`'i kullanmaya devam edin.

Gemini 3.8 Flash'ı çağırmak için ücretli bir hesaba ihtiyacım var mı? Hayır. Ücretsiz bir AI Studio anahtarı, hız limitleri ve Google'ın veri kullanım koşullarıyla birlikte çalışır. Ücretsiz kullanım kılavuzu, ücretsiz katmanın size ne vereceğini ve ne vermeyeceğini listeler, buna Gemini uygulamasının 3.8 Flash için bir AI Pro veya Ultra planı gerektirdiği gerçeği de dahildir.

3.8 Flash, 3.7 Flash'tan daha yavaş mı? Jeton başına hayır. Google'dan Logan Kilpatrick, hızın yaklaşık olarak aynı olduğunu söyledi ve Artificial Analysis saniyede yaklaşık 300 çıkış jetonu ölçtü. Görev başına, `high` seviyesinde daha uzun sürüyor (çalışmalarında 2,5 dakikaya karşı 2,2 dakika) çünkü daha fazla jeton üretiyor.

Gemini 3.7 Flash'ı çağırmaya devam edebilir miyim? Evet. Google, 3.7 Flash'ın "tamamen desteklenmeye devam ettiğini" belirtiyor ve herhangi bir kullanımdan kaldırma tarihi yayınlamadı. Eğer 3.8 Flash'taki ek jeton harcaması iş yükünüzde size bir şey kazandırmıyorsa, yerinizde kalmak geçerli bir seçenektir.

3.8 Flash, Live API'yi veya görüntü oluşturmayı destekliyor mu? Hayır. Yalnızca metin çıktısı verir. Ses oluşturma, görüntü oluşturma ve Live API bu modelde desteklenmiyor.

Sırada ne var

Artık iki çalışan çağrı yoluna, çoklu dönüş desenine ve bir jeton kullanım kontrolüne sahipsiniz. Buradan, fonksiyon çağırma kılavuzuyla araçları bağlayın, düşünme seviyeleri gönderisiyle yol başına seviyelerinizi belirleyin ve hala geçiş yapıp yapmama konusunda kararsızsanız, 3.8 ile 3.7 Flash karşılaştırması avantaj ve dezavantajları ortaya koyar. Maliyet kaymasının başarısız bir test olarak görünmesi için Apidog senaryosunu çalışır durumda tutun.