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

Gemini 3.8 Flash API: Interactions API, düşünme seviyeleri ve maliyet kontrolü

Google, Gemini 3.8 Flash'ı 2 Eylül 2026'da yayınladı. API model kimliği, önizleme eki olmayan düz bir dizedir: gemini-3.8-flash. Model, 31 Aralık 2026'ya kadar Gemini 3.7 Flash ile aynı tanıtım fiyatını koruyor: milyon giriş jetonu başına 0,75 dolar ve milyon çıkış jetonu başına 3,75 dolar. Google'ın ifadesiyle daha fazla çalışan bir model; karmaşık görevlerde daha fazla muhakeme adımı atıyor ve araçları daha sık çağırıyor. Bu davranış, jeton faturanızda görülebilir. Modelin genel özellikleri ve kıyaslamaları için Gemini 3.8 Flash nedir? yazısına göz atın.

Apidog'u bugün deneyin

Bu kılavuzda çalışan bir entegrasyon kuracağız:

• Google AI Studio üzerinden API anahtarı alma
• Interactions API ile ilk isteği gönderme
• Eski generateContent yolunu kullanma
• Her iki API'de thinking_level konumunu belirleme
• Akış yanıtlarını ve thoughtsTokenCount değerini izleme
• İstekleri Apidog üzerinde test etme

Tüm çağrılar düz JSON üzerinden HTTP ile yapılır. Bu nedenle uygulama kodunu yazmadan önce istekleri Apidog'da oluşturup doğrulayabilirsiniz. Google'ın lansman duyurusu da modelin resmi çerçevesini sunuyor.

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

Öğe	Değer
Model kimliği	gemini-3.8-flash
Birincil uç nokta	POST /v1beta/interactions
Eski uç nokta	POST /v1beta/models/gemini-3.8-flash:generateContent
Kimlik doğrulama başlığı	x-goog-api-key
Bağlam / çıktı	1.048.576 giriş jetonu / 65.536 çıkış jetonu
Girdiler	Metin, görüntü, video, ses, PDF
Çıktı	Yalnızca metin
Düşünme seviyeleri	low, medium (varsayılan), high
Tanıtım fiyatı	31 Aralık 2026'ya kadar milyon jeton başına 0,75 $ / 3,75 $
1 Ocak 2027 sonrası fiyat	Milyon jeton başına 1,50 $ / 7,50 $

İki ayrıntı özellikle önemli:

1. Varsayılan düşünme seviyesi high değil, medium'dur.
2. Düşünme jetonları çıkış jetonu olarak ücretlendirilir. Bu nedenle düşünme seviyesi yalnızca kalite ayarı değil, aynı zamanda bir maliyet kararıdır. Ayrıntılı hesaplamalar için Gemini 3.8 Flash fiyatlandırma dökümüne bakabilirsiniz.

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

Google AI Studio'yu açın, Google hesabınızla oturum açın ve API anahtarları sayfasından yeni bir anahtar oluşturun.

Anahtar, hız limitleriyle birlikte ücretsiz katmanda hemen çalışır. Google, ücretsiz katmandaki verilerin ürünlerini geliştirmek için kullanılabileceğini belirtir. Üretim limitleri için faturalandırma hesabı bağlayarak 1. Katmana geçebilirsiniz.

Anahtarı kaynak koda yazmak yerine ortam değişkeni olarak dışa aktarın:

export GEMINI_API_KEY="AIza..."

Resmi Python SDK'sı GEMINI_API_KEY değerini ortamdan okur. Bu nedenle genai.Client() herhangi bir argüman gerektirmez:

pip install google-genai

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

Google, Interactions API'yi Gemini 3.x modelleri için birincil API olarak konumlandırıyor. İstek; model, input ve isteğe bağlı generation_config alanlarından oluşan tek bir JSON nesnesidir.

cURL

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -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 yürütme adımlarından oluşur. Model düşünceleri ve araç çağrıları ayrı adımlar olarak döner; son adım, metni içeren model_output adımıdır.

Python SDK

SDK bu yapıyı 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 değerlerini eklemeyin. Google, Gemini 3 modellerinde temperature değerinin varsayılanı olan 1.0 olarak bırakılmasını öneriyor. Daha düşük bir değer döngülere veya performans düşüşüne yol açabilir.

Eski bir modelden yapılandırma kopyaladıysanız, silmeniz gereken ilk satır genellikle temperature olur.

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

Interactions API, varsayılan olarak konuşma durumunu sunucuda saklar. Bir konuşmayı sürdürmek için önceki yanıtın id değerini previous_interaction_id olarak gönderin:

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)

Konuşma geçmişini yeniden göndermeniz gerekmez.

Uyumluluk kurallarınız sunucu tarafında veri saklanmasını yasaklıyorsa store: false kullanın. Bu durumda konuşma durumunu kendiniz yönetmeniz gerekir. Modelin düşünce bloklarını ve düşünce imzalarını her dönüşte aldığınız biçimde geri göndermeniz de gerekir. Araç kullanırken aynı kural, Gemini 3.8 Flash fonksiyon çağırma kılavuzunda açıklanıyor.

Adım 4: Eski generateContent yolu

Üretimdeki birçok Gemini uygulaması hâlâ generateContent kullanıyor. Google bu yolu eski olarak adlandırıyor, ancak herhangi bir sona erme tarihi vermeden tamamen desteklemeye devam ediyor. Bu nedenle mevcut entegrasyonunuzu hemen yeniden yazmanız gerekmiyor.

Gemini 3.7 Flash API kılavuzunda kullanılan yapı 3.8 Flash için de aynıdır. Farklı olan nokta, düşünme ayarının farklı bir alanda bulunmasıdır.

generateContent isteğinde seviye, camelCase kullanılarak generationConfig.thinkingConfig.thinkingLevel altında verilir.

cURL

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

Python SDK

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)

thinking_budget kullanan eski bir yapılandırmadan geçiyorsanız, tamsayı değerini dize enum'u ile değiştirin. Gemini 3 ve sonraki sürümlerde candidate_count da kaldırılmıştır.

Geçiş öncesi ve sonrası JSON yapılarını karşılaştıran tam kontrol listesi için 3.7'den 3.8 Flash'a geçiş kılavuzuna bakın.

API alanları karşılaştırması

Endişe	Interactions API	Eski generateContent
Düşünme seviyesi	generation_config.thinking_level	generationConfig.thinkingConfig.thinkingLevel
Konuşma durumu	previous_interaction_id ile sunucu tarafında	Tüm contents dizisini yeniden gönderin
Araç sonucu	call_id + name ile function_result	id + name ile functionResponse
Son metin	model_output adımı veya SDK'da output_text	candidates[0].content.parts[].text
Düşünce imzaları	store: false olmadıkça SDK tarafından yönetilir	Her parçayı geldiği biçimde geri gönderin

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

Sohbet arayüzlerinde akış almak için yöntemi streamGenerateContent olarak 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ının sonunda usageMetadata bulunur:

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

Burada özellikle thoughtsTokenCount değerini izleyin. Düşünme jetonları tanıtım döneminde milyon başına 3,75 dolar üzerinden çıkış jetonu olarak faturalandırılır. Google, daha yüksek çaba seviyelerinde modelin performansı artırmak için daha fazla jeton kullanabileceğini belirtiyor.

Artificial Analysis, high seviyesindeki testlerde görev başına yaklaşık 48 bin çıkış jetonu ölçtü. Bu değer Gemini 3.7 Flash'a göre %30 daha yüksek olduğundan, jeton fiyatları aynı kalsa da görev başına maliyet yaklaşık 0,40 dolardan 0,58 dolara çıktı. Aynı çalışmada medium ve low seviyeleri için görev başına maliyetler sırasıyla 0,41 ve 0,24 dolar olarak ölçüldü. Seviyeleri iş yüküne göre seçmek için düşünme seviyeleri kılavuzunu kullanın.

Modelin nasıl muhakeme ettiğine dair özetleri görmek için thinkingConfig içine aşağıdaki alanı ekleyin:

{
  "includeThoughts": true
}

Düşünce özetleri "thought": true ile işaretlenmiş parçalar olarak döner. Kullanıcıya gösterilen yanıtı oluştururken bu parçaları atlayın.

İlk saatte karşılaşabileceğiniz hatalar

minimal düşünme seviyesi desteklenmiyor

Gemini 3.8 Flash yalnızca low, medium ve high seviyelerini destekler. minimal göndermek şu hatayla birlikte 400 INVALID_ARGUMENT döndürür:

Bu model için MINIMAL düşünme seviyesi desteklenmiyor.
Lütfen başka bir düşünme seviyesiyle tekrar deneyin.

Düzeltme tek kelimeliktir: minimal yerine low kullanın. Eski 3.x yapılandırmaları ve kopyalanan kod parçaları bu hatanın yaygın kaynaklarıdır.

429 yanıtı

429, genellikle hata değil, hesabınızın hız limitine ulaştığınız anlamına gelir. Güncel limitleri Google'ın hız limitleri sayfasından kontrol edin:

• Ücretsiz katman sınırlı hızla çalışır.
• 1. Katman için faturalandırma hesabı bağlanır.
• 2. Katman için 100 dolar harcama ve üç gün gerekir.
• 3. Katman için 1.000 dolar harcama ve 30 gün gerekir.

Model başına dakika başına istek ve jeton limitleri hesap bazında gösterildiğinden, bir blog yazısındaki sayılara güvenmek yerine AI Studio'daki kendi limitlerinizi kontrol edin.

429 aldığınızda:

1. Üstel geri çekilme uygulayın.
2. İsteği yeniden deneyin.
3. Düşük hacimde tekrar eden hatalarda katmanınızı yükseltin.

Çevrimdışı işler için Batch API daha uygun olabilir. Batch API %50 indirim sunar; tanıtım döneminde fiyatlar milyon jeton başına 0,375 dolar / 1,875 dolardır. Kendi kuyruğa alınmış jeton limitleri 1. Katmanda 3 milyon, 2. Katmanda 400 milyon ve 3. Katmanda 1 milyardır. İstek biçimi için Gemini toplu mod kılavuzuna bakın.

Fonksiyon sonucunda call_id eksik

Araç kullanıyorsanız her Interactions API function_result nesnesi hem call_id hem de name taşımalıdır. Eski functionResponse biçiminde ise eşleşen id ve name alanları gerekir.

Bu alanlardan herhangi birini atlamak, araç dönüşünün başarısız olmasına neden olur.

Yayına almadan önce iki uç noktayı Apidog'da test edin

Terminal çağrıları çalıştıktan sonra istekleri ekibinizin çalıştırabileceği paylaşılabilir bir koleksiyona taşıyın. Apidog'u indirin, bir proje oluşturun ve iki uç noktayı kayıtlı istek olarak ekleyin.

1. API anahtarını isteğin dışında tutun

GEMINI_API_KEY değerini ortam değişkeni olarak tanımlayın ve başlıkta şu biçimde kullanın:

x-goog-[REDACTED CREDENTIAL]}}

Böylece kaydedilmiş isteklerde sır saklanmaz. Ücretsiz katman anahtarı ile faturalandırılmış anahtar arasında geçiş yapmak da tek bir ortam değişikliğiyle mümkün olur.

2. Durum kodunu ve jeton kullanımını doğrulayın

Her istek için şu iddiaları ekleyin:

• HTTP durumunun 200 olması
• usageMetadata.thoughtsTokenCount değerinin belirlediğiniz üst sınırın altında kalması

Bu üst sınır, maliyet regresyonu alarmınızdır. İstem değişikliği veya sessiz bir model güncellemesi düşünme jetonlarını artırırsa, fatura gelmeden önce test başarısız olur.

Akış varyantını test etmek için SSE test kılavuzuna bakın. Apidog, SSE yanıtını ham parçalar yerine birleştirilmiş olay akışı olarak işler.

3. Aynı istemi üç seviyede çalıştırın

Aynı isteği low, medium ve high seviyeleriyle çoğaltın. Ardından şu değerleri karşılaştırın:

• thoughtsTokenCount
• Yanıt süresi
• Sonuç kalitesi

Bu yaklaşım, genel benchmark ortalamaları yerine kendi istemleriniz için gerçek maliyet ve performans verilerini sağlar.

4. Testleri planlayın

İstekleri bir test senaryosuna dönüştürüp programa göre çalıştırın. Böylece:

• Hız limiti değişiklikleri
• minimal seviyesinin kaldırılması gibi doğrulama değişiklikleri
• Düşünme jetonlarındaki artışlar

üretimde değil, test raporlarında görünür. Apidog'da API testlerinin nasıl planlanacağını öğrenin.

Apidog modeli çalıştırmaz ve SDK'yı değiştirmez. Bunun yerine HTTP çağrılarını kaydedilebilir, paylaşılabilir ve iddialarla doğrulanabilir hâle getirir.

SSS

Yeni projeler hangi uç noktayı kullanmalı?

Yeni projeler için Interactions API'yi kullanın. Google generateContent'i eski olarak adlandırıyor ve hâlâ tamamen destekliyor; ancak yeni özellikler önce Interactions API'ye geliyor. Sunucu tarafı durum yönetimi de çoklu dönüş kodunu kısaltıyor.

Mevcut hizmetleriniz için geçiş gerektiren bir neden yoksa generateContent kullanmaya devam edebilirsiniz.

Gemini 3.8 Flash'ı çağırmak için ücretli hesap gerekir mi?

Hayır. Ücretsiz AI Studio anahtarı çalışır; ancak hız limitleri ve Google'ın veri kullanım koşulları geçerlidir. Gemini 3.8 Flash'ı ücretsiz kullanma kılavuzu, ücretsiz katmanın kapsamını ve Gemini uygulamasında 3.8 Flash kullanmak için AI Pro veya Ultra planı gerektiğini açıklar.

3.8 Flash, 3.7 Flash'tan daha mı yavaş?

Jeton başına hayır. Google'dan Logan Kilpatrick, hızın yaklaşık olarak aynı olduğunu belirtti. Artificial Analysis saniyede yaklaşık 300 çıkış jetonu ölçtü.

Görev başına high seviyesi daha uzun sürüyor: ilgili testlerde yaklaşık 2,5 dakika yerine 2,2 dakika. Bunun nedeni hızın düşmesi değil, daha fazla jeton üretilmesi.

Gemini 3.7 Flash'ı kullanmaya devam edebilir miyim?

Evet. Google, Gemini 3.7 Flash'ın tamamen desteklenmeye devam ettiğini ve herhangi bir kullanımdan kaldırma tarihi açıklanmadığını belirtiyor.

3.8 Flash'ın ek jeton maliyeti iş yükünüzde anlamlı bir kazanım sağlamıyorsa, 3.7 Flash'ta kalmak geçerli bir seçenektir. Ayrıntılı değerlendirme için Gemini 3.8 Flash ve 3.7 Flash karşılaştırmasına bakın.

3.8 Flash, Live API'yi veya görüntü oluşturmayı destekliyor mu?

Hayır. Model yalnızca metin çıktısı verir. Ses oluşturma, görüntü oluşturma ve Live API desteklenmez.

Sırada ne var?

Artık şunlara sahipsiniz:

• Interactions API ve generateContent için çalışan çağrı örnekleri
• previous_interaction_id ile çoklu dönüş deseni
• Düşünme seviyesi seçimi
• thoughtsTokenCount tabanlı maliyet kontrolü
• Apidog üzerinde paylaşılabilir API testleri

Sonraki adım olarak araçları fonksiyon çağırma kılavuzuyla bağlayın ve her iş yükü için seviyelerinizi düşünme seviyeleri kılavuzuna göre belirleyin.

Geçiş kararınızı doğrulamak için Apidog senaryosunu çalışır durumda tutun. Böylece maliyet artışı, başarısız bir test olarak görünür; üretim faturası geldiğinde sürpriz olmaz.