Cara Menggunakan API Gemini 4 Hydrogen

API Gemini 4 Hydrogen menggunakan ID model gemini-4-hydrogen. Anda memanggilnya dengan POST ke https://generativelanguage.googleapis.com/v1beta/interactions, dengan key Anda di header x-goog-api-key, serta model dan input di body JSON. Model ini tersedia di tier gratis maupun tier berbayar ($1,50 input, $7,50 output per 1 juta token) dan secara default menggunakan tingkat berpikir high.

Panduan ini membahas seluruh alurnya: key, request pertama, tingkat berpikir, PDF, function calling, streaming, dan penanganan error. Semua nama field diambil langsung dari dokumentasi Google.

Apa saja yang Anda butuhkan sebelum pemanggilan API Gemini 4 Hydrogen pertama?

Anda membutuhkan API key Gemini, ID model gemini-4-hydrogen, dan endpoint Interactions. Google merilis Hydrogen pada 12 November 2026 sebagai model Gemini 4 yang cepat, melengkapi Carbon dan Argon (apa itu Gemini 4 Hydrogen).

Dokumentasi Google menyebut generateContent sebagai legacy, jadi contoh-contoh di sini menggunakan Interactions.

Bagaimana cara mendapatkan API key Gemini untuk Hydrogen?

Hydrogen berada di tier gratis, sehingga Anda bisa mulai tanpa penagihan:

1. Buka halaman API keys di Google AI Studio.
2. Klik Create API key. Key baru yang dibuat di AI Studio adalah authorization key, yang terikat ke service account.
3. Ekspor key tersebut: export GEMINI_API_KEY="YOUR_API_KEY". SDK membaca GEMINI_API_KEY atau GOOGLE_API_KEY; jika keduanya diatur, GOOGLE_API_KEY yang diprioritaskan.
4. Cloud project yang dibuat di luar AI Studio mungkin perlu verifikasi proyek sebelum tier gratis bisa digunakan.

Google mempublikasikan angka tier gratis di halaman rate limits, bukan di panduan peluncuran. Panduan Gemini 4 Hydrogen gratis kami membahas apa saja yang Anda dapatkan dengan $0.

Bagaimana cara mengirim request API Gemini 4 Hydrogen pertama Anda?

Kirim model dan input ke endpoint Interactions. Simpan nama model dalam variabel agar mengganti model hanya perlu mengubah satu baris.

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."
  }'

Panggilan yang sama dengan Python SDK (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)

Responsnya berisi id, status, dan array steps. Teks berada di step model_output, penalaran di step thought, dan output_text dari SDK menggabungkan teksnya untuk Anda. Objek usage memuat total_input_tokens, total_thought_tokens, total_output_tokens, dan total_tokens.

Snippet ini mengikuti quickstart Google. Kami tidak menjalankannya untuk tulisan ini (tidak ada key Gemini di mesin pengujian kami), jadi pastikan bentuknya cocok dengan respons pertama Anda sendiri.

Bagaimana cara mengatur tingkat berpikir Gemini 4 Hydrogen?

Atur thinking_level di dalam generation_config. Hydrogen secara default menggunakan high, menambahkan tingkat baru xhigh, dan menolak minimal dengan error.

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
    }
  }'

Ada dua aturan penting. max_output_tokens membatasi thinking dan output secara bersamaan, sehingga batas lama yang rendah (misalnya 8.192) bisa memotong jawaban; Google menyarankan untuk menaikkannya ke 65.536 dan menurunkan tingkat berpikir sebagai gantinya. Dan token thinking ditagih dengan tarif output $7,50, sehingga xhigh lebih mahal meskipun panjang jawaban yang terlihat sama. Rincian harga Gemini 4 Hydrogen menghitung angkanya per tingkat.

Google juga menyatakan bahwa server mengabaikan temperature, top_p, dan top_k pada Hydrogen, jadi hapus saja dari request Anda.

Bagaimana cara mengirim PDF ke Gemini 4 Hydrogen?

Tambahkan item document ke array input, di samping item text yang berisi instruksi Anda. Untuk file kecil, kirim PDF secara inline sebagai base64:

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."}
    ]
  }'

Untuk file yang lebih besar atau penggunaan berulang di beberapa giliran, unggah sekali dengan Files API (gratis, disimpan 48 jam) dan gunakan {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"} sebagai gantinya. Menurut panduan pemrosesan dokumen, PDF bisa hingga 50 MB atau 1.000 halaman, dan model membaca grafik, tabel, serta gambar di dalamnya, bukan hanya teksnya.

Bagaimana cara kerja function calling dengan Gemini 4 Hydrogen?

Deklarasikan fungsi Anda di tools. Model tidak menjalankan apa pun; ia mengembalikan step function_call, kode Anda menjalankan fungsinya, lalu Anda mengirim kembali function_result. Ini adalah langkah pertama, dari panduan function calling Google:

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"]
      }
    }]
  }'

Temukan step yang type-nya function_call dan baca name, arguments, dan id-nya. Jalankan fungsi Anda, lalu kirim hasilnya kembali pada sesi yang sama:

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 menyimpan status percakapan dan thinking di sisi Google, sehingga Anda tidak perlu mengirim ulang riwayatnya. Satu peringatan dari catatan migrasi Google: meminta model untuk mencetak "tool calls" berupa JSON mentah tanpa ada tool yang dideklarasikan bisa mengembalikan MALFORMED_FUNCTION_CALL. Deklarasikan tool secara native atau gunakan structured outputs.

Bagaimana cara melakukan streaming respons Gemini 4 Hydrogen?

Tambahkan "stream": true ke body. API menjawab dengan Server-Sent Events:

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
  }'

Menurut panduan streaming Google, Anda menerima interaction.created, lalu step.start, step.delta, dan step.stop untuk setiap step (thought, lalu model_output), kemudian interaction.completed dengan usage akhir. Gabungkan delta.text dari step model_output untuk membangun jawabannya. Streaming tidak menaikkan batas atas: setiap hop tetap berhenti di 65.536 token. Untuk output yang lebih panjang, atur "background": true dengan max_output_tokens di atas 65.536 dan lakukan polling ke GET /v1beta/interactions/{id} sampai status keluar dari in_progress atau queued.

Bagaimana cara menangani error API Gemini 4 Hydrogen?

Error non-streaming dikembalikan sebagai status HTTP plus objek error yang berisi code dan message. Dalam stream, Anda menerima event error dengan field yang sama. Kode yang paling sering Anda temui, dari halaman error API Google:

Panduan troubleshooting Google menyarankan untuk hanya melakukan retry pada 429, 408, dan 5xx, dengan exponential backoff plus jitter dan batas jumlah retry, dan jangan pernah untuk 400, 402, atau 403. Python SDK sudah otomatis melakukan retry pada error transien hingga empat kali.

Minta coding agent Anda menguji API Hydrogen dengan Apidog CLI

Alih-alih membaca JSON setelah setiap perubahan prompt atau tingkat berpikir, minta coding agent Anda (Claude Code, Codex, Cursor) membangun pengujian yang dapat diulang dan menjalankannya dengan Apidog CLI.

Atur sekali saja:

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

Lalu beri agent Anda satu prompt:

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.

Agent memeriksa setiap payload terhadap skema CLI sebelum menulis apa pun:

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

Kedua eksekusi tersebut membandingkan thought token untuk prompt yang sama, yaitu angka yang memengaruhi tagihan Anda. Ganti -r cli,json dengan -r junit dan eksekusi yang sama bisa masuk ke CI; panduan CI/CD Apidog CLI menunjukkan pipelinenya dan Apidog CLI di Claude Code membahas setup agent-nya. Paket Free Apidog mencakup hingga 4 pengguna.

FAQ

Apa ID model Gemini 4 Hydrogen? gemini-4-hydrogen. Berfungsi dengan Interactions API dan generateContent.

Apakah API Gemini 4 Hydrogen gratis? Ya, dengan batasan. Google mencantumkan Hydrogen di tier gratis Gemini API dan AI Studio, dengan rate limit. Penggunaan berbayar dikenai biaya $1,50 per 1 juta token input dan $7,50 per 1 juta token output.

Bagaimana cara migrasi dari Gemini 3.8 Flash? Ubah string model, naikkan batas max_output_tokens yang rendah, hapus temperature, top_p, top_k, dan explicit caching (cachedContents), serta ganti thinking minimal dengan low atau medium.

Apakah Hydrogen mendukung context caching? Hanya implicit caching. Fitur ini berjalan secara default pada prompt dengan minimal 4.096 token dan memberi diskon 95% untuk cache hit. Explicit caching tidak didukung.

Apa perbedaan Hydrogen dengan Gemini 4 Argon di API? Skema request-nya sama. Hydrogen secara default menggunakan high dan menambahkan xhigh, sedangkan Argon secara default menggunakan medium. Lihat panduan API Gemini 4 Argon, panduan API Gemini 4 Carbon, dan Gemini 4 Hydrogen Orchestrator untuk memadankan model-model ini.