TL;DR
Gemini 4 Hydrogen API tersedia melalui Gemini API milik Google dan gateway pihak ketiga yang didukung seperti CometAPI. Tentukan rutenya terlebih dahulu: gunakan Google untuk fitur spesifik penyedia dan kontrol akun, atau gunakan CometAPI saat Anda menginginkan gateway model terpadu atau klien yang kompatibel dengan OpenAI. Mulailah dengan permintaan teks kecil, lalu tambahkan streaming, riwayat percakapan, file, dan alat.
Anda memerlukan Python 3.10 atau lebih baru, kunci untuk rute yang dipilih, dan akses ke gemini-4-hydrogen. Contoh JavaScript opsional menggunakan Node.js 22 atau lebih baru. Simpan kredensial di lingkungan server sepanjang tutorial.
Key Takeaways
- Gunakan
gemini-4-hydrogensebagai ID model untuk Gemini 4 Hydrogen API. - Google dan CometAPI memiliki kredensial dan penagihan terpisah. Cocokkan kunci dengan endpoint yang Anda pilih.
- Mulai dengan GenerateContent native; gunakan antarmuka CometAPI yang kompatibel dengan OpenAI bila sesuai dengan klien chat yang sudah ada.
- Simpan respons model lengkap dalam riwayat multi-giliran, termasuk signature, sebelum mengembalikan tindak lanjut atau hasil alat.
- Bandingkan penggunaan token aktual dan tugas yang terselesaikan saat memilih rute; contoh harga token standar muncul di bagian harga.
What Is the Gemini 4 Hydrogen API?
Google memperkenalkan Hydrogen pada 12 November 2026. API ini menerima prompt dan file yang didukung, lalu mengembalikan teks yang dihasilkan atau panggilan fungsi terstruktur untuk ditangani oleh aplikasi Anda. Anda tidak perlu meng-host model sendiri.
Mulailah dengan permintaan hanya-teks dan verifikasi teks yang dikembalikan, alasan penyelesaian, dan penggunaan token sebelum menambahkan alat atau file. Setelah ini berfungsi, tambahkan status percakapan atau alat bisnis hanya-baca alih-alih membangun seluruh alur kerja sekaligus.
Gemini 4 Hydrogen API specifications
| Specification | Kemampuan model yang didokumentasikan Google |
|---|---|
| Model ID | gemini-4-hydrogen |
| Input | Teks, gambar, audio, video, dan dokumen yang didukung |
| Output | Teks, dengan bagian panggilan fungsi terstruktur saat alat digunakan |
| Unified context budget | 1,048,576 token di seluruh input dan output |
| Single foreground output segment | Hingga 65,536 token, termasuk penalaran dan panggilan fungsi |
| Application features | Kontrol tingkat penalaran, keluaran terstruktur, dan pemanggilan fungsi |
Ini adalah kemampuan model, bukan jaminan bahwa setiap gateway mengekspos setiap fitur penyedia. Contoh di bawah menggunakan field permintaan standar dan generasi latar depan singkat.
Google Official API vs CometAPI
Kedua rute mendukung permintaan Gemini, tetapi menggunakan endpoint, kredensial, dan sistem penagihan yang berbeda. Gunakan Google untuk fitur spesifik penyedia; gunakan CometAPI untuk gateway terpadu atau klien kompatibel yang sudah ada.
| Decision | API Resmi Google Gemini Developer | Integrasi Gemini CometAPI |
|---|---|---|
| Native API host | generativelanguage.googleapis.com | api.cometapi.com |
| API key in this guide | GEMINI_API_KEY | COMETAPI_KEY |
| Account and billing | Dikelola melalui Google | Dikelola melalui CometAPI |
| Best starting point | Fitur spesifik Google dan kontrol akun | Akses model terpadu atau klien kompatibel OpenAI yang sudah ada |
Gunakan prompt dan anggaran output yang sama saat memeriksa kedua rute agar hasilnya berguna untuk dibandingkan. Alternatif JavaScript dan yang kompatibel dengan OpenAI tetap dikonfigurasi secara eksplisit untuk CometAPI.
How to Use Gemini 4 Hydrogen API Step by Step?
Step 1: Create an API key
Untuk CometAPI, buat akun dan hasilkan kunci di API token console. Untuk akses langsung Google, buat kunci Gemini API di Google AI Studio. Konfirmasikan akses model dan penagihan akun yang dipilih atau kuota yang tersedia.
Simpan kunci dengan aman. Kunci CometAPI tidak dapat mengautentikasi permintaan ke endpoint Google, dan kunci Google tidak dapat mengautentikasi permintaan CometAPI.
Setel kunci untuk rute yang Anda pilih di Bash; Anda hanya perlu salah satu penetapan ini.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Setel kunci yang sesuai di PowerShell pada Windows.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
Step 2: Send a first request with cURL
Kirim permintaan teks native melalui CometAPI dari terminal Bash.
curl "https://api.cometapi.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Atau, kirim permintaan native yang sama langsung ke Google dengan kunci Google API.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Setelah permintaan berhasil, verifikasi tiga field: candidates[0].content.parts untuk teks yang terlihat, finishReason untuk status penyelesaian, dan usageMetadata untuk penggunaan token. Perbaiki kesalahan autentikasi atau permintaan sebelum menambahkan lebih banyak kode aplikasi.
Step 3: Configure the Python Client and Send a Request
Instal paket yang digunakan oleh contoh Python.
python -m pip install requests openai
Simpan helper ini sebagai hydrogen_client.py. Biarkan PROVIDER disetel ke cometapi untuk CometAPI, atau setel ke google untuk akses langsung Gemini Developer API. Contoh native berikut mengimpor file ini, sehingga mereka mempertahankan rute yang dipilih.
Konfigurasikan endpoint yang dipilih dan definisikan helper permintaan dan teks yang dapat digunakan ulang.
import os
import requests
MODEL = "gemini-4-hydrogen"
PROVIDER = "cometapi" # Change to "google" for direct access.
ROUTES = {
"cometapi": ("https://api.cometapi.com", "COMETAPI_KEY"),
"google": ("https://generativelanguage.googleapis.com", "GEMINI_API_KEY"),
}
BASE_URL, KEY_NAME = ROUTES[PROVIDER]
API_KEY = os.environ[KEY_NAME]
URL = f"{BASE_URL}/v1beta/models/{MODEL}:generateContent"
def generate(payload):
response = requests.post(
URL,
headers={"x-goog-api-key": API_KEY},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
def visible_text(data):
candidates = data.get("candidates") or []
if not candidates:
raise ValueError("No candidate returned; inspect promptFeedback.")
candidate = candidates[0]
parts = candidate.get("content", {}).get("parts", [])
text = "".join(
part.get("text", "") for part in parts
if not part.get("thought", False)
)
if not text:
raise ValueError(
f"No visible text; inspect parts and finishReason: "
f"{candidate.get('finishReason')}"
)
return text
Simpan berikut ini sebagai hydrogen.py di samping helper. Skrip ini mencetak jawaban, alasan penyelesaian, dan penggunaan sehingga Anda dapat membedakan jawaban yang selesai dari output yang berhenti pada batas token.
Kirim permintaan teks menggunakan penyedia yang dikonfigurasi.
from hydrogen_client import generate, visible_text
data = generate({
"contents": [{"role": "user", "parts": [{
"text": "Explain API rate limiting in three sentences."
}]}],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
},
})
print(visible_text(data))
candidate = data["candidates"][0]
print("Finish reason:", candidate.get("finishReason"))
print("Usage:", data.get("usageMetadata", {}))
Jalankan skrip di terminal tempat Anda menyetel kunci API yang dipilih.
python hydrogen.py
Baca jawabannya, lalu periksa finishReason untuk melihat alasan generasi berhenti. Di usageMetadata, periksa berapa banyak token yang digunakan permintaan. MAX_TOKENS berarti respons mungkin tidak lengkap, meskipun permintaan HTTP berhasil.
Use JavaScript or an OpenAI-Compatible Client
Pilih contoh yang sesuai dengan aplikasi Anda. Contoh Node.js mengirim permintaan Gemini native. Jika Anda sudah menggunakan OpenAI SDK, lewati ke contoh Python di bawah.
JavaScript with Node.js
Simpan berikut ini sebagai hydrogen.js dan jalankan node hydrogen.js. Ini mengirim bentuk permintaan native yang sama dan mengekstrak semua bagian teks yang terlihat.
Kirim permintaan GenerateContent native dari Node.js.
const apiKey = process.env.COMETAPI_KEY;
if (!apiKey) throw new Error("Set COMETAPI_KEY before running this script.");
const baseUrl = "https://api.cometapi.com";
const model = "gemini-4-hydrogen";
async function main() {
const response = await fetch(
`${baseUrl}/v1beta/models/${model}:generateContent`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-goog-api-key": apiKey
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [
{
text: "Explain how an AI coding agent works."
}
]
}
],
generationConfig: {
maxOutputTokens: 4096,
thinkingConfig: {
thinkingLevel: "MEDIUM"
}
}
})
}
);
if (!response.ok) {
throw new Error(
`API error: ${response.status} ${await response.text()}`
);
}
const data = await response.json();
const candidate = data.candidates?.[0];
const text = (candidate?.content?.parts || [])
.filter(part => !part.thought)
.map(part => part.text || "")
.join("");
if (!text) {
throw new Error(`No visible text; finishReason=${candidate?.finishReason}`);
}
console.log(text);
}
main().catch(console.error);
Python with the OpenAI SDK
Jika aplikasi Anda sudah menggunakan OpenAI SDK, CometAPI juga mengekspos POST /v1/chat/completions. Migrasi paling sederhana adalah mengganti kunci API, base URL, dan ID model. Gunakan rute ini untuk alur kerja chat umum; gunakan endpoint Gemini-native saat Anda membutuhkan field khusus penyedia Gemini.
Buat permintaan Chat Completions melalui CometAPI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
response = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": "Explain how an AI coding agent works."
}
]
)
print(response.choices[0].message.content)
Contoh native menggunakan contents dan generationConfig; Chat Completions menggunakan messages dan field permintaannya sendiri. Pertahankan setiap permintaan dalam satu format, jangan menyalin field native ke dalam panggilan SDK yang tidak menerimanya.
Advanced Gemini 4 Hydrogen API Features
Contoh berikut menggunakan kembali hydrogen_client.py dari bagian penyiapan, sehingga berfungsi dengan penyedia yang dipilih di PROVIDER. Contoh streaming di bawah menggunakan klien CometAPI Chat Completions terpisah, yang sesuai untuk aplikasi yang kompatibel dengan OpenAI.
Configure reasoning and structured output
Gunakan generationConfig untuk menyetel thinkingConfig.thinkingLevel ke LOW, MEDIUM, HIGH, atau XHIGH. Pilih anggaran output yang menyisakan ruang untuk penalaran dan jawaban yang terlihat. Saat aplikasi mengharapkan JSON, gunakan responseMimeType dan responseSchema alih-alih hanya mengandalkan permintaan pemformatan bahasa alami.
Setel anggaran output dan tingkat penalaran untuk permintaan native.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Stream responses through CometAPI
Streaming mengembalikan konten yang dihasilkan secara bertahap alih-alih menunggu jawaban lengkap. Ini berguna untuk antarmuka chat, asisten coding, dan aplikasi di mana latensi yang dirasakan penting.
CometAPI mendokumentasikan streaming Chat Completions dengan stream=true. Contoh Python menangani potongan tanpa choices, yang dapat terjadi dalam respons streaming.
Cetak teks saat tiba melalui endpoint yang kompatibel dengan OpenAI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
stream = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": (
"Write a Python function that validates an email "
"address and explain the main checks."
)
}
],
stream=True
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta and delta.content:
print(delta.content, end="", flush=True)
print()
Untuk klien native, CometAPI mendokumentasikan streamGenerateContent dengan Server-Sent Events. Rute itu mengembalikan objek respons GenerateContent, bukan delta Chat Completions. Pertahankan parser sesuai rute; perilaku streaming dapat berbeda antara endpoint Gemini native dan gateway yang kompatibel dengan OpenAI. Uji rute Hydrogen yang persis digunakan aplikasi Anda sebelum memigrasikan klien streaming yang ada.
Preserve multi-turn conversation history
Kirim giliran pengguna dan model sebelumnya dengan permintaan berikutnya. Simpan objek konten model lengkap alih-alih membangunnya kembali dari teks yang terlihat; ini mempertahankan metadata yang dikembalikan untuk giliran berikutnya. Simpan contoh sebagai hydrogen_history.py di samping helper bersama.
Buat dua permintaan terkait sambil mempertahankan respons model pertama yang lengkap.
from hydrogen_client import generate, visible_text
history = [{"role": "user", "parts": [{
"text": "Suggest a simple queue-based background job architecture."
}]}]
config = {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
}
first = generate({"contents": history, "generationConfig": config})
print(visible_text(first))
candidate = first["candidates"][0]
if candidate.get("finishReason") != "STOP":
raise RuntimeError("The first turn did not finish normally.")
history.append(candidate["content"])
history.append({"role": "user", "parts": [{
"text": "Now identify three failure scenarios in that design."
}]})
second = generate({"contents": history, "generationConfig": config})
print(visible_text(second))
print("Finish reason:", second["candidates"][0].get("finishReason"))
Jalankan python hydrogen_history.py. Jawaban kedua seharusnya membahas desain dari giliran pertama. Pertahankan prefiks percakapan sebelumnya tidak berubah dalam contoh ini; aplikasi jangka panjang memerlukan kebijakan terpisah untuk kompaksi dan batas konteks.
Send images and PDFs
Hydrogen mendukung pemahaman gambar dan dokumen. Dalam format permintaan Gemini native, tambahkan bagian inlineData bersama instruksi teks. Ini berguna untuk analisis tangkapan layar, diagram arsitektur, formulir hasil scan, dan ekstraksi laporan.
Simpan contoh ini sebagai analyze_file.py di samping hydrogen_client.py. Ini mengirim satu gambar lokal atau PDF, sehingga Anda dapat menggunakan ulang kode yang sama untuk kedua input. Gunakan file kecil untuk permintaan pertama; Base64 meningkatkan ukuran permintaan.
Analisis PNG, JPEG, atau PDF lokal menggunakan klien native bersama.
import base64
import sys
from pathlib import Path
from hydrogen_client import generate, visible_text
path = Path(sys.argv[1])
mime_types = {
".png": "image/png", ".jpg": "image/jpeg",
".jpeg": "image/jpeg", ".pdf": "application/pdf",
}
mime_type = mime_types.get(path.suffix.lower())
if mime_type is None:
raise ValueError("Choose a PNG, JPEG, or PDF file.")
data = generate({
"contents": [{"role": "user", "parts": [
{"text": "Summarize this file and identify the key findings."},
{"inlineData": {
"mimeType": mime_type,
"data": base64.b64encode(path.read_bytes()).decode("ascii"),
}},
]}],
"generationConfig": {"maxOutputTokens": 4096},
})
print(visible_text(data))
Jalankan contoh file dengan dokumen atau gambar Anda sendiri.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
Byte file harus sesuai dengan MIME type yang dideklarasikan. Mengganti nama ekstensi file tidak mengonversi file. Jika unggahan ditolak, periksa error untuk batas ukuran atau format sebelum mencoba lagi; jangan berasumsi URI file yang di-host Google dapat diakses melalui gateway pihak ketiga.
Connect application-controlled tools
Function calling memungkinkan model meminta operasi yang dilakukan aplikasi Anda. Model mengembalikan panggilan fungsi terstruktur; aplikasi Anda memvalidasi argumen, mengeksekusi fungsi, dan mengirim kembali hasilnya.
Contoh ini menggunakan basis data pesanan kecil fiksi. Simpan sebagai order_agent.py di samping klien bersama. Ini mengimplementasikan perjalanan bolak-balik, membatasi loop hingga empat permintaan, dan mempertahankan konten model lengkap—termasuk signature yang dikembalikan—antar giliran.
Jalankan loop function-calling terbatas terhadap basis data demo lokal.
from hydrogen_client import generate, visible_text
orders = {"DEMO-1001": {"status": "shipped", "carrier": "Example Carrier"}}
tools = [{"functionDeclarations": [{
"name": "lookup_order",
"description": "Retrieve a demonstration order by its order ID.",
"parameters": {
"type": "OBJECT",
"properties": {"order_id": {"type": "STRING"}},
"required": ["order_id"],
},
}]}]
history = [{"role": "user", "parts": [{
"text": "Use lookup_order to check the status of DEMO-1001."
}]}]
for _ in range(4):
data = generate({
"contents": history,
"tools": tools,
"generationConfig": {"maxOutputTokens": 4096},
})
candidates = data.get("candidates") or []
if not candidates or not candidates[0].get("content"):
raise RuntimeError("No model content returned.")
model_content = candidates[0]["content"]
calls = [
part["functionCall"] for part in model_content.get("parts", [])
if "functionCall" in part
]
if not calls:
print(visible_text(data))
break
history.append(model_content) # Preserve all parts and signatures.
results = []
for call in calls:
args = call.get("args", {})
order_id = args.get("order_id") if isinstance(args, dict) else None
if call.get("name") != "lookup_order":
raise ValueError("Unexpected function name.")
if not isinstance(order_id, str) or not order_id:
raise ValueError("order_id must be a non-empty string.")
result = orders.get(order_id, {"error": "Order not found"})
reply = {"name": call["name"], "response": result}
if "id" in call:
reply["id"] = call["id"]
results.append({"functionResponse": reply})
history.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool-call limit reached before a final answer.")
Jalankan python order_agent.py. Jawaban akhir harus mencerminkan catatan lokal untuk DEMO-1001. Dalam layanan nyata, otorisasi pengguna sebelum mengakses pesanan; pilihan ID pesanan oleh model bukan bukti izin.
How Much Does Gemini 4 Hydrogen API Cost?
Tarif di bawah ini adalah USD per satu juta token, dicek pada 17 November 2026. Tarif membandingkan input dan output standar tanpa cache, bukan batch, prioritas, input cache, atau penggunaan alat yang ditagih terpisah.
| Token type | Standar Global Google | Gemini 4 Hydrogen API di CometAPI |
|---|---|---|
| Input tokens / 1M | $1.50 | $1.20 |
| Output tokens / 1M | $7.50 | $6.00 |
Untuk 100.000 token input dan 10.000 token output yang ditagih, estimasi CometAPI adalah 0.1 × $1.20 + 0.01 × $6.00 = $0.18. Volume yang sama pada tarif standar yang tercantum Google berharga $0.225, selisih 20%. Sertakan token penalaran dalam penggunaan output dan periksa penggunaan yang ditagih di akun Anda saat memperkirakan alur kerja nyata.
How Do You Migrate to Gemini 4 Hydrogen API?
What Changes When Migrating from Gemini 3.8 Flash?
Sebelum Anda mengubah ID model, periksa pengaturan penalaran, anggaran konteks, dan riwayat percakapan yang dikirim klien Anda dengan setiap permintaan.
| Integration detail | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| Default thinking level | MEDIUM | HIGH |
| Context accounting | Batas input dan output terpisah | Satu anggaran input/output bersama |
| Multi-turn state | Tinjau penanganan riwayat klien yang ada | Pertahankan bagian model dan signature lengkap; pengeditan prefiks memerlukan penanganan khusus |
Perubahan migrasi yang didokumentasikan (https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-4-hydrogen) paling penting saat aplikasi Anda bergantung pada default, mengompakkan riwayat, atau menjalankan beberapa putaran alat. Setel penalaran secara eksplisit dan uji alur kerja pendek yang ada sebelum mengganti model produksi.
Update an existing integration
Buat konfigurasi uji dengan ID model baru sambil menjaga kunci dan endpoint tetap bersama. Jalankan alur kerja representatif yang sama dengan kedua konfigurasi sehingga Anda dapat membandingkan perilakunya.
- Kirim permintaan teks baru dan verifikasi alasan penyelesaian serta penggunaan tokennya.
- Putar ulang tugas multi-giliran dan perjalanan alat bolak-balik menggunakan objek respons model lengkap.
- Hapus kontrol yang tidak kompatibel yang tercantum di bagian keterbatasan sebelum membandingkan hasil permintaan.
- Latih jalur rollback Anda dalam percakapan baru; jangan berasumsi model lain menerima metadata penalaran yang disimpan Hydrogen.
Decide whether the migration helps your workload
Adopsi konfigurasi baru saat memenuhi target kualitas dan latensi tugas dengan biaya per tugas yang diselesaikan yang dapat diterima. Jika klien saat ini sudah memenuhi target tersebut, gunakan pilot terbatas untuk menetapkan manfaat sebelum memindahkan setiap permintaan. Pertahankan prompt, input, dan kriteria penilaian tetap konsisten selama evaluasi.
Gemini 4 Hydrogen API Limitations
Hydrogen developer guide menjelaskan pembatasan yang memengaruhi klien yang ada. Atasi hal ini dalam konstruksi permintaan alih-alih mengulang payload yang sama yang ditolak.
- Field yang tidak didukung: hapus thinkingBudget, thinkingLevel disetel ke MINIMAL, frequencyPenalty, presencePenalty, dan candidateCount lebih dari satu.
- Pengaturan sampling diabaikan: temperature kustom, topP, dan topK tidak mengendalikan output Hydrogen.
- Caching:
cachedContenteksplisit tidak didukung. Prefiks prompt yang stabil dapat menggunakan caching implisit, tetapi itu tidak menetapkan diskon cache khusus gateway. - Output panjang: klien contoh di panduan ini hanya mengimplementasikan permintaan sinkron. Tidak mencakup decode panjang di latar belakang atau alur kerja kelanjutan khusus penyedia.
- Perubahan percakapan: memodifikasi prompt sebelumnya atau definisi alat dapat membuat status penalaran tidak valid. Pertahankan prefiks, atau terapkan perilaku ketidakcocokan prefiks yang didokumentasikan untuk rute yang dipilih.
Common setup checks
| Symptom | First check |
|---|---|
| 401 or 403 | Konfirmasikan bahwa kredensial milik endpoint dan memiliki akses ke model yang dipilih. |
| 400 | Baca body error; periksa field yang tidak didukung, JSON yang salah bentuk, dan metadata percakapan. |
| No visible text | Periksa promptFeedback, bagian kandidat, dan finishReason; respons mungkin diblokir, tidak lengkap, atau meminta alat. |
| MAX_TOKENS | Perlakukan teks sebagai berpotensi tidak lengkap dan tinjau anggaran output sebelum menerimanya. |
| File request rejected | Verifikasi MIME type yang sebenarnya dan batas payload rute yang dipilih. |
Untuk kegagalan tak terduga, catat model, rute, status, timestamp, dan ID permintaan bila tersedia. Jaga kunci API dan konten file sensitif tetap di luar log rutin.
FAQ
How should I retry Gemini 4 Hydrogen API rate-limit errors?
Untuk HTTP 429, kurangi konkurensi dan lakukan retry dengan backoff eksponensial dan jitter, dengan jumlah upaya maksimum yang tetap. Simpan ID permintaan saat gateway menyediakannya. Jangan retry permintaan tidak valid atau kegagalan autentikasi tanpa perubahan; panduan error dan retry CometAPI membedakan hal itu dari kegagalan sementara. Timeout dapat terjadi setelah pemrosesan dimulai, jadi lindungi tindakan sisi aplikasi dari eksekusi ganda.
Can I call Gemini 4 Hydrogen API directly from a web app?
Rutekan permintaan melalui backend Anda sendiri. Kunci yang disematkan di JavaScript frontend dapat diekstraksi oleh pengunjung, bahkan jika kodenya dibundel atau diminifikasi. Biarkan backend mengautentikasi pengguna, menerapkan batas penggunaan, dan mengirim permintaan model. Untuk streaming, teruskan respons bertahap ke browser tanpa mengekspos kunci API hulu.
How should I handle an interrupted Gemini 4 Hydrogen stream?
Perlakukan teks yang diterima sebagai hasil parsial hingga respons selesai. Permintaan baru memulai generasi baru; tidak secara otomatis melanjutkan stream yang terputus pada token yang sama. Simpan output parsial terpisah dari jawaban yang di-retry, dan jangan mengeksekusi tindakan dari JSON yang tidak lengkap atau argumen alat yang belum selesai. Tawarkan tindakan retry yang terlihat alih-alih diam-diam menggabungkan dua generasi.
Conclusion
Gunakan tugas yang representatif sebagai pemeriksaan penerimaan pertama Anda: permintaan harus berhasil, aplikasi harus mengekstrak hasil yang dimaksud, dan penggunaan token yang tercatat harus sesuai dengan anggaran Anda. Tambahkan satu fitur pada satu waktu dan pertahankan pemeriksaan tersebut dalam rangkaian integrasi Anda. Klien kecil yang terlihat lebih mudah diperluas daripada alur kerja besar yang kegagalannya sulit dilacak.

