Gemini 4 Hydrogen API Nasıl Kullanılır?

Gemini 4 Hydrogen API, gemini-4-hydrogen model kimliğini kullanır. Modele https://generativelanguage.googleapis.com/v1beta/interactions adresine bir POST isteğiyle, anahtarınızı x-goog-api-key başlığında ve model ile input alanlarını JSON gövdesinde göndererek çağırırsınız. Hem ücretsiz hem de ücretli katmanda çalışır (girdi için 1M token başına 1,50 $, çıktı için 7,50 $) ve varsayılan olarak high düşünme seviyesini kullanır.

Bu rehber tüm süreci adım adım anlatır: anahtar alma, ilk istek, düşünme seviyesi, PDF gönderme, function calling, akış (streaming) ve hata yönetimi. Tüm alan adları Google’ın dokümantasyonundan alınmıştır.

İlk Gemini 4 Hydrogen API çağrınızdan önce nelere ihtiyacınız var?

Bir Gemini API anahtarına, gemini-4-hydrogen model kimliğine ve Interactions uç noktasına ihtiyacınız var. Google, Hydrogen’ı 12 Kasım 2026’da Carbon ve Argon’un yanında hızlı Gemini 4 modeli olarak piyasaya sürdü (Gemini 4 Hydrogen nedir).

Google’ın dokümanları generateContent’i eski (legacy) olarak nitelendiriyor, dolayısıyla bu örneklerde Interactions kullanılır.

Hydrogen için Gemini API anahtarını nasıl alırsınız?

Hydrogen ücretsiz katmanda yer aldığı için faturalandırmayı etkinleştirmeden başlayabilirsiniz:

1. Google AI Studio’da API keys sayfasını açın.
2. Create API key düğmesine tıklayın. AI Studio’da oluşturulan yeni anahtarlar, bir servis hesabına bağlı yetkilendirme anahtarlarıdır.
3. Anahtarı dışa aktarın: export GEMINI_API_KEY="YOUR_API_KEY". SDK’lar GEMINI_API_KEY veya GOOGLE_API_KEY değişkenini okur; ikisi de tanımlıysa GOOGLE_API_KEY öncelik kazanır.
4. AI Studio dışında oluşturulmuş bir Cloud projesi, ücretsiz katmanın çalışabilmesi için proje doğrulamasına ihtiyaç duyabilir.

Google, ücretsiz katman limitlerini başlatma rehberinde değil, rate limits sayfasında yayınlar. Gemini 4 Hydrogen ücretsiz rehberimiz, 0 $ karşılığında neler elde ettiğinizi ele alır.

İlk Gemini 4 Hydrogen API isteğinizi nasıl gönderirsiniz?

model ve input alanlarını Interactions uç noktasına gönderin. Modeli bir değişkende tutun ki model değiştirmek tek satırlık bir düzenleme olsun.

export GEMINI_MODEL="gemini-4-hydrogen"

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "'"$GEMINI_MODEL"'",
    "input": "Write a Python function that retries an HTTP call with exponential backoff."
  }'

Python SDK ile aynı çağrı (pip install -U google-genai):

import os
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model=os.environ.get("GEMINI_MODEL", "gemini-4-hydrogen"),
    input="Write a Python function that retries an HTTP call with exponential backoff.",
)

print(interaction.output_text)
print(interaction.usage)

Yanıt bir id, bir status ve bir steps dizisi taşır. Metin model_output adımlarında, akıl yürütme thought adımlarında yer alır; SDK’nın output_text alanı ise metni sizin için birleştirir. usage nesnesi total_input_tokens, total_thought_tokens, total_output_tokens ve total_tokens değerlerini içerir.

Bu kod parçacıkları Google’ın hızlı başlangıç kılavuzunu takip eder. Bu yazı için bunları çalıştırmadık (test makinemizde Gemini anahtarı yoktu), bu yüzden şekli kendi ilk yanıtınızla karşılaştırın.

Gemini 4 Hydrogen düşünme seviyesini nasıl ayarlarsınız?

thinking_level alanını generation_config içinde ayarlayın. Hydrogen varsayılan olarak high kullanır, yeni bir xhigh seviyesi ekler ve minimal değerini hata vererek reddeder.

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Audit this payment retry queue for race conditions.",
    "generation_config": {
      "thinking_level": "medium",
      "max_output_tokens": 65536
    }
  }'

İki kural önemlidir. max_output_tokens hem düşünmeyi hem de çıktıyı birlikte sınırlar; bu yüzden eski, düşük bir limit (örneğin 8.192) yanıtları yarıda kesebilir. Google, bunun yerine limiti 65.536’ya yükseltip düşünme seviyesini düşürmenizi önerir. Ayrıca düşünme tokenları 7,50 $’lık çıktı ücretiyle faturalandığı için, görünen yanıt aynı uzunlukta olsa bile xhigh daha pahalıya mal olur. Gemini 4 Hydrogen fiyatlandırma analizi, her seviye için rakamları hesaplar.

Google ayrıca sunucunun Hydrogen’da temperature, top_p ve top_k parametrelerini yok saydığını belirtir; dolayısıyla bu parametreleri isteklerinizden çıkarın.

Gemini 4 Hydrogen’a PDF nasıl gönderilir?

input dizisine, talimatınızı içeren bir text öğesinin yanına bir document öğesi ekleyin. Küçük dosyalar için PDF’i base64 olarak satır içinde (inline) gönderin:

PDF_PATH="invoice.pdf"
B64=$(base64 < "$PDF_PATH" | tr -d '\n')

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-4-hydrogen",
    "input": [
      {"type": "document", "data": "'"$B64"'", "mime_type": "application/pdf"},
      {"type": "text", "text": "Extract the line items as a table."}
    ]
  }'

Daha büyük dosyalar veya birden fazla turda yeniden kullanım için, dosyayı bir kez Files API ile yükleyin (ücretsizdir, 48 saat saklanır) ve bunun yerine {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"} değerini iletin. Belge işleme rehberine göre PDF’ler en fazla 50 MB veya 1.000 sayfa olabilir ve model bunlardaki yalnızca metni değil, grafikleri, tabloları ve görselleri de okur.

Gemini 4 Hydrogen ile function calling nasıl çalışır?

Fonksiyonunuzu tools içinde tanımlayın. Model hiçbir şeyi çalıştırmaz; bir function_call adımı döndürür, sizin kodunuz fonksiyonu çalıştırır ve siz de bir function_result geri gönderirsiniz. Google’ın function calling rehberinden ilk adım:

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-4-hydrogen",
    "input": "What'\''s the temperature in London?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }'

type değeri function_call olan adımı bulun ve name, arguments ve id değerlerini okuyun. Fonksiyonunuzu çalıştırın, ardından sonucu aynı oturum üzerinden geri gönderin:

fc = next(s for s in interaction.steps if s.type == "function_call")
result = get_current_temperature(**fc.arguments)

final = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[{
        "type": "function_result",
        "name": fc.name,
        "call_id": fc.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
    tools=[weather_function],
    previous_interaction_id=interaction.id,
)
print(final.output_text)

previous_interaction_id, sohbet ve düşünme durumunu Google tarafında tutar; böylece geçmişi yeniden göndermeniz gerekmez. Google’ın geçiş notlarından bir uyarı: hiçbir araç tanımlanmadan, modelden ham JSON “tool call” çıktısı yazmasını istemek MALFORMED_FUNCTION_CALL hatası döndürebilir. Araçları doğal olarak (native) tanımlayın veya yapılandırılmış çıktıları kullanın.

Gemini 4 Hydrogen yanıtlarını nasıl akıtarsınız (streaming)?

Gövdeye "stream": true ekleyin. API, Server-Sent Events ile yanıt verir:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Explain idempotency keys in three short paragraphs.",
    "stream": true
  }'

Google’ın streaming rehberine göre önce interaction.created olayı gelir; ardından her adım için (önce thought, sonra model_output) step.start, step.delta ve step.stop, en sonunda da nihai usage bilgisiyle birlikte interaction.completed gelir. Yanıtı oluşturmak için model_output adımlarındaki delta.text değerlerini birleştirin. Streaming üst sınırı yükseltmez: her istekte yine 65.536 token durur. Daha uzun çıktılar için "background": true ayarını 65.536’nın üzerinde bir max_output_tokens değeriyle kullanın ve status değeri in_progress veya queued olmaktan çıkana kadar GET /v1beta/interactions/{id} uç noktasını yoklayın.

Gemini 4 Hydrogen API hatalarını nasıl yönetirsiniz?

Streaming olmayan hatalar, bir HTTP durum kodu ve code ile message alanlarını içeren bir error nesnesi olarak döner. Bir akışta, aynı alanlara sahip bir error olayı alırsınız. Google’ın API errors sayfasından, en sık karşılaşacağınız kodlar:

Google’ın sorun giderme rehberi, yalnızca 429, 408 ve 5xx hatalarını; üstel gecikme (exponential backoff) ve jitter ekleyerek, bir yeniden deneme üst sınırıyla denemenizi, 400, 402 veya 403 hatalarını ise asla denememenizi önerir. Python SDK, geçici hataları zaten dört kez yeniden dener.

Kodlama ajanınız Hydrogen API’sini Apidog CLI ile test etsin

Her istek veya düşünme seviyesi değişikliğinden sonra JSON okumak yerine, kodlama ajanınızın (Claude Code, Codex, Cursor) tekrarlanabilir bir test oluşturmasına ve bunu Apidog CLI ile çalıştırmasına izin verin.

Bir kez kurun:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Ardından ajanınıza tek bir istem verin:

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY and
THINKING (default "low"). Add an endpoint for POST /v1beta/interactions with the
x-goog-api-key header from GEMINI_API_KEY. Create a test case that sends model
"gemini-4-hydrogen", a short prompt and generation_config.thinking_level
{{THINKING}}, and asserts: HTTP 200, status is "completed", steps contains a
non-empty model_output, and usage.total_tokens exists. Run it at low and at high,
then compare usage.total_thought_tokens.

Ajan, herhangi bir şey yazmadan önce her gönderiyi CLI’nın şemalarına göre kontrol eder:

apidog environment create gemini --project <projectId> --base-url https://generativelanguage.googleapis.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "THINKING=low" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "THINKING=high" -r cli,json

İki çalıştırma, aynı istem için düşünme tokenlarını — yani faturanızı etkileyen sayıyı — karşılaştırır. -r cli,json yerine -r junit yazarsanız aynı çalıştırma CI’a girer; Apidog CLI CI/CD rehberi pipeline’ı gösterir ve Claude Code’da Apidog CLI ajan kurulumunu ele alır. Apidog’un Ücretsiz planı 4 kullanıcıya kadar kapsar.

SSS

Gemini 4 Hydrogen model kimliği nedir? gemini-4-hydrogen. Hem Interactions API hem de generateContent ile çalışır.

Gemini 4 Hydrogen API ücretsiz mi? Evet, limitler dâhilinde. Google, Hydrogen’ı Gemini API ve AI Studio’nun ücretsiz katmanında, hız sınırlı olarak listeliyor. Ücretli kullanım, 1M girdi tokenı için 1,50 $ ve 1M çıktı tokenı için 7,50 $ tutarındadır.

Gemini 3.8 Flash’tan nasıl geçiş yaparım? Model dizesini değiştirin, düşük max_output_tokens limitlerini yükseltin, temperature, top_p, top_k ve açık önbellekleme (cachedContents) parametrelerini kaldırın ve minimal düşünme seviyesini low veya medium ile değiştirin.

Hydrogen bağlam önbellekleme (context caching) destekliyor mu? Yalnızca örtük önbellekleme destekleniyor. Varsayılan olarak en az 4.096 tokenlık istemlerde devreye girer ve önbellek isabetlerinde %95 indirim sağlar. Açık (explicit) önbellekleme desteklenmiyor.

Hydrogen, API tarafında Gemini 4 Argon’dan nasıl farklı? İstek şeması aynı. Hydrogen varsayılan olarak high kullanır ve xhigh ekler; Argon ise varsayılan olarak medium kullanır. Modelleri birlikte kullanmak için Gemini 4 Argon API rehberine, Gemini 4 Carbon API rehberine ve Gemini 4 Hydrogen Orchestrator sayfasına bakın.