TL;DR
API Gemini 4 Hydrogen khả dụng qua Gemini API của Google và các cổng bên thứ ba được hỗ trợ như CometAPI. Hãy chọn tuyến trước: dùng Google để có các tính năng riêng của nhà cung cấp và kiểm soát tài khoản, hoặc dùng CometAPI khi bạn muốn một cổng mô hình thống nhất hoặc client tương thích OpenAI. Bắt đầu với một yêu cầu văn bản nhỏ, sau đó thêm streaming, lịch sử hội thoại, tệp và công cụ.
Bạn cần Python 3.10 trở lên, một khóa cho tuyến đã chọn và quyền truy cập vào gemini-4-hydrogen. Ví dụ JavaScript tùy chọn dùng Node.js 22 trở lên. Giữ thông tin xác thực trong môi trường máy chủ xuyên suốt hướng dẫn.
Key Takeaways
- Dùng
gemini-4-hydrogenlàm ID mô hình cho Gemini 4 Hydrogen API. - Google và CometAPI có thông tin xác thực và hệ thống thanh toán riêng. Ghép khóa với endpoint bạn chọn.
- Bắt đầu với GenerateContent gốc; dùng giao diện tương thích OpenAI của CometAPI khi phù hợp với client chat hiện có.
- Giữ đầy đủ phản hồi mô hình trong lịch sử nhiều lượt, gồm cả chữ ký, trước khi trả lời tiếp theo hoặc kết quả công cụ.
- So sánh mức dùng token thực tế và nhiệm vụ hoàn thành khi chọn tuyến; ví dụ giá token chuẩn nằm trong phần giá.
What Is the Gemini 4 Hydrogen API?
Google giới thiệu Hydrogen vào ngày 12 tháng 11 năm 2026. API nhận prompt và các tệp được hỗ trợ, rồi trả về văn bản sinh hoặc các lời gọi hàm có cấu trúc để ứng dụng của bạn xử lý. Bạn không cần tự lưu trữ mô hình.
Bắt đầu với một yêu cầu chỉ văn bản và xác minh văn bản trả về, lý do kết thúc và mức dùng token trước khi thêm công cụ hoặc tệp. Khi bước này hoạt động, thêm trạng thái hội thoại hoặc một công cụ doanh nghiệp chỉ đọc thay vì xây dựng toàn bộ quy trình cùng lúc.
Gemini 4 Hydrogen API specifications
| Specification | Google-documented model capability |
|---|---|
| Model ID | gemini-4-hydrogen |
| Input | Văn bản, hình ảnh, âm thanh, video và tài liệu được hỗ trợ |
| Output | Văn bản, với phần gọi hàm có cấu trúc khi dùng công cụ |
| Unified context budget | 1.048.576 token cho cả input và output |
| Single foreground output segment | Tối đa 65.536 token, gồm cả suy luận và gọi hàm |
| Application features | Kiểm soát mức độ suy nghĩ, đầu ra có cấu trúc và gọi hàm |
Đây là khả năng của mô hình, không đảm bảo mọi cổng đều cung cấp đầy đủ tính năng của nhà cung cấp. Ví dụ bên dưới dùng các trường yêu cầu chuẩn và các phần sinh tiền cảnh ngắn.
Google Official API vs CometAPI
Cả hai tuyến đều hỗ trợ yêu cầu Gemini, nhưng dùng endpoint, thông tin xác thực và hệ thống thanh toán khác nhau. Dùng Google cho các tính năng riêng của nhà cung cấp; dùng CometAPI cho cổng thống nhất hoặc client tương thích OpenAI hiện có.
| Decision | Google Gemini Developer API | CometAPI Gemini integration |
|---|---|---|
| Native API host | generativelanguage.googleapis.com | api.cometapi.com |
| API key in this guide | GEMINI_API_KEY | COMETAPI_KEY |
| Account and billing | Quản lý qua Google | Quản lý qua CometAPI |
| Best starting point | Tính năng riêng của Google và kiểm soát tài khoản | Truy cập mô hình thống nhất hoặc client tương thích OpenAI hiện có |
Giữ cùng prompt và ngân sách đầu ra khi kiểm tra hai tuyến để kết quả so sánh hữu ích. Ví dụ JavaScript và phương án tương thích OpenAI được cấu hình rõ ràng cho CometAPI.
How to Use Gemini 4 Hydrogen API Step by Step?
Step 1: Create an API key
Với CometAPI, tạo tài khoản và tạo khóa trong bảng điều khiển token API. Với truy cập trực tiếp Google, tạo khóa Gemini API trong Google AI Studio. Xác nhận quyền truy cập mô hình và thanh toán hoặc hạn ngạch khả dụng của tài khoản đã chọn.
Lưu khóa an toàn. Khóa CometAPI không thể xác thực yêu cầu tới endpoint của Google, và khóa Google không thể xác thực yêu cầu CometAPI.
Đặt khóa cho tuyến đã chọn trong Bash; bạn chỉ cần một trong hai lệnh gán này.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Đặt khóa tương ứng trong PowerShell trên 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
Gửi yêu cầu văn bản gốc qua CometAPI từ 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"
}
}
}'
Hoặc gửi cùng yêu cầu gốc trực tiếp tới Google bằng khóa 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"
}
}
}'
Sau khi yêu cầu thành công, hãy xác minh ba trường: candidates[0].content.parts cho văn bản hiển thị, finishReason cho trạng thái hoàn thành và usageMetadata cho mức dùng token. Sửa lỗi xác thực hoặc lỗi yêu cầu trước khi thêm nhiều mã ứng dụng hơn.
Step 3: Configure the Python Client and Send a Request
Cài đặt các gói dùng trong ví dụ Python.
python -m pip install requests openai
Lưu helper này thành hydrogen_client.py. Để PROVIDER là cometapi cho CometAPI, hoặc đặt thành google cho truy cập trực tiếp Gemini Developer API. Các ví dụ gốc sau đó import file này, nên chúng giữ tuyến đã chọn.
Cấu hình endpoint đã chọn và định nghĩa các helper yêu cầu và văn bản có thể tái sử dụng.
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
Lưu đoạn sau thành hydrogen.py bên cạnh helper. Nó in câu trả lời, lý do hoàn thành và mức dùng để bạn phân biệt câu trả lời hoàn tất với đầu ra dừng ở giới hạn token.
Gửi yêu cầu văn bản bằng nhà cung cấp đã cấu hình.
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", {}))
Chạy script trong terminal nơi bạn đã đặt khóa API đã chọn.
python hydrogen.py
Đọc câu trả lời, rồi kiểm tra finishReason để biết lý do dừng sinh. Trong usageMetadata, kiểm tra số lượng token yêu cầu đã dùng. MAX_TOKENS nghĩa là phản hồi có thể chưa đầy đủ, ngay cả khi yêu cầu HTTP thành công.
Use JavaScript or an OpenAI-Compatible Client
Chọn ví dụ phù hợp với ứng dụng của bạn. Ví dụ Node.js gửi yêu cầu Gemini gốc. Nếu ứng dụng của bạn đã dùng OpenAI SDK, hãy chuyển tới ví dụ Python bên dưới.
JavaScript với Node.js
Lưu đoạn sau thành hydrogen.js và chạy node hydrogen.js. Nó gửi cùng dạng yêu cầu gốc và trích xuất tất cả phần văn bản hiển thị.
Gửi yêu cầu GenerateContent gốc từ 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 với OpenAI SDK
Nếu ứng dụng của bạn đã dùng OpenAI SDK, CometAPI cũng cung cấp POST /v1/chat/completions. Cách di chuyển đơn giản nhất là đổi khóa API, base URL và ID mô hình. Dùng tuyến này cho các workflow chat phổ biến; dùng endpoint gốc của Gemini khi bạn cần các trường riêng của Gemini.
Tạo yêu cầu Chat Completions qua 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)
Các ví dụ gốc dùng contents và generationConfig; Chat Completions dùng messages và các trường yêu cầu riêng. Giữ mỗi yêu cầu theo một định dạng thay vì sao chép các trường gốc vào một gọi SDK không chấp nhận chúng.
Advanced Gemini 4 Hydrogen API Features
Các ví dụ sau tái sử dụng hydrogen_client.py từ phần thiết lập, nên chúng hoạt động với nhà cung cấp đã chọn trong PROVIDER. Ví dụ streaming bên dưới dùng client Completions Chat riêng của CometAPI, phù hợp với ứng dụng tương thích OpenAI hiện có.
Configure reasoning and structured output
Dùng generationConfig để đặt thinkingConfig.thinkingLevel thành LOW, MEDIUM, HIGH hoặc XHIGH. Chọn ngân sách đầu ra chừa chỗ cho cả suy luận và câu trả lời hiển thị. Khi ứng dụng kỳ vọng JSON, dùng responseMimeType và responseSchema thay vì chỉ dựa vào yêu cầu định dạng ngôn ngữ tự nhiên.
Đặt ngân sách đầu ra và mức suy luận cho một yêu cầu gốc.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Stream responses through CometAPI
Streaming trả về nội dung sinh dần thay vì đợi câu trả lời hoàn chỉnh. Hữu ích cho giao diện chat, trợ lý viết mã và ứng dụng nơi độ trễ cảm nhận quan trọng.
CometAPI có tài liệu streaming Chat Completions với stream=true. Ví dụ Python xử lý các chunk không có choices, điều có thể xảy ra trong phản hồi streaming.
In văn bản khi nó đến qua endpoint tương thích 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()
Với client gốc, CometAPI có tài liệu streamGenerateContent với Server-Sent Events. Tuyến đó trả về đối tượng phản hồi GenerateContent thay vì các delta Chat Completions. Giữ bộ phân tích khớp với tuyến; hành vi streaming có thể khác giữa endpoint gốc Gemini và cổng tương thích OpenAI. Hãy thử đúng tuyến Hydrogen mà ứng dụng của bạn dùng trước khi di chuyển client streaming hiện có.
Preserve multi-turn conversation history
Gửi các lượt người dùng và mô hình trước đó cùng với yêu cầu tiếp theo. Giữ toàn bộ đối tượng nội dung của mô hình thay vì dựng lại từ văn bản hiển thị; điều này bảo toàn metadata trả về cho lượt tiếp theo. Lưu ví dụ thành hydrogen_history.py bên cạnh helper dùng chung.
Thực hiện hai yêu cầu liên quan trong khi bảo toàn phản hồi mô hình đầu tiên đầy đủ.
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"))
Chạy python hydrogen_history.py. Câu trả lời thứ hai nên đề cập tới thiết kế từ lượt đầu tiên. Giữ tiền tố hội thoại trước đó không đổi trong ví dụ này; các ứng dụng chạy lâu cần chính sách riêng cho việc nén và giới hạn ngữ cảnh.
Send images and PDFs
Hydrogen hỗ trợ hiểu hình ảnh và tài liệu. Trong định dạng yêu cầu gốc của Gemini, thêm một phần inlineData bên cạnh phần hướng dẫn văn bản. Điều này hữu ích cho phân tích ảnh chụp màn hình, sơ đồ kiến trúc, biểu mẫu quét và trích xuất báo cáo.
Lưu ví dụ này thành analyze_file.py bên cạnh hydrogen_client.py. Nó gửi một hình ảnh hoặc PDF cục bộ, nên bạn có thể tái sử dụng cùng mã cho cả hai đầu vào. Dùng tệp nhỏ cho yêu cầu đầu tiên; Base64 làm tăng kích thước yêu cầu.
Phân tích PNG, JPEG hoặc PDF cục bộ bằng client gốc dùng chung.
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))
Chạy ví dụ tệp với tài liệu hoặc hình ảnh của bạn.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
Byte của tệp phải khớp với MIME type đã khai báo. Đổi tên phần mở rộng tệp không chuyển đổi tệp. Nếu tải lên bị từ chối, kiểm tra lỗi để tìm giới hạn kích thước hoặc định dạng trước khi thử lại; đừng giả định URI tệp lưu trữ bởi Google có thể truy cập qua cổng bên thứ ba.
Connect application-controlled tools
Gọi hàm cho phép mô hình yêu cầu một thao tác mà ứng dụng của bạn thực hiện. Mô hình trả về một lời gọi hàm có cấu trúc; ứng dụng của bạn xác thực tham số, thực thi hàm và gửi kết quả lại.
Ví dụ này dùng một cơ sở dữ liệu đơn hàng nhỏ, hư cấu. Lưu thành order_agent.py bên cạnh client dùng chung. Nó triển khai vòng lặp khứ hồi, giới hạn vòng lặp ở bốn yêu cầu, và bảo toàn nội dung mô hình đầy đủ—bao gồm bất kỳ chữ ký trả về—giữa các lượt.
Chạy vòng lặp gọi hàm có giới hạn với cơ sở dữ liệu demo cục bộ.
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.")
Chạy python order_agent.py. Câu trả lời cuối cùng nên phản ánh bản ghi cục bộ cho DEMO-1001. Trong dịch vụ thực tế, hãy ủy quyền người dùng trước khi truy cập đơn hàng; việc mô hình chọn một ID đơn hàng không phải bằng chứng về quyền.
How Much Does Gemini 4 Hydrogen API Cost?
Mức giá dưới đây là USD cho một triệu token, kiểm tra ngày 17 tháng 11 năm 2026. Chúng so sánh input và output chuẩn không cache, không bao gồm batch, ưu tiên, input cache hoặc mức dùng công cụ tính phí riêng.
| Token type | Google Global Standard | Gemini 4 Hydrogen API in CometAPI |
|---|---|---|
| Input tokens / 1M | $1.50 | $1.20 |
| Output tokens / 1M | $7.50 | $6.00 |
Với 100.000 token đầu vào và 10.000 token đầu ra tính phí, ước tính CometAPI là 0.1 × $1.20 + 0.01 × $6.00 = $0.18. Cùng khối lượng ở mức giá chuẩn niêm yết của Google là $0.225, chênh lệch 20%. Bao gồm token suy luận trong mức dùng output và kiểm tra mức dùng bị tính phí trong tài khoản khi ước lượng workflow thực tế.
How Do You Migrate to Gemini 4 Hydrogen API?
What Changes When Migrating from Gemini 3.8 Flash?
Trước khi đổi ID mô hình, kiểm tra thiết lập suy luận, ngân sách ngữ cảnh và lịch sử hội thoại mà client của bạn gửi kèm mỗi yêu cầu.
| Integration detail | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| Default thinking level | MEDIUM | HIGH |
| Context accounting | Giới hạn input và output tách biệt | Một ngân sách chung cho input/output |
| Multi-turn state | Xem lại cách client hiện tại xử lý lịch sử | Bảo toàn đầy đủ các phần nội dung và chữ ký của mô hình; sửa tiền tố cần xử lý đặc biệt |
Các thay đổi di trú được tài liệu quan trọng nhất khi ứng dụng của bạn phụ thuộc vào mặc định, nén lịch sử hoặc chạy nhiều lượt công cụ. Đặt suy luận rõ ràng và thử một workflow ngắn hiện có trước khi đổi mô hình sản xuất.
Update an existing integration
Tạo cấu hình thử nghiệm với ID mô hình mới đồng thời giữ khóa và endpoint của nó cùng nhau. Chạy cùng workflow đại diện với cả hai cấu hình để bạn có thể so sánh hành vi.
- Gửi yêu cầu văn bản mới và xác minh lý do hoàn thành và mức dùng token.
- Phát lại một nhiệm vụ nhiều lượt và một vòng khứ hồi công cụ dùng đối tượng phản hồi mô hình đầy đủ.
- Loại bỏ các điều khiển không tương thích được liệt kê trong phần giới hạn trước khi so sánh kết quả yêu cầu.
- Thử đường lui của bạn trong một hội thoại mới; đừng giả định mô hình khác chấp nhận metadata suy luận đã lưu của Hydrogen.
Decide whether the migration helps your workload
Áp dụng cấu hình mới khi nó đáp ứng chất lượng và độ trễ mục tiêu với chi phí chấp nhận được cho mỗi nhiệm vụ hoàn thành. Nếu client hiện tại đã đáp ứng các mục tiêu đó, hãy dùng thử nghiệm giới hạn để xác nhận lợi ích trước khi chuyển mọi yêu cầu. Giữ prompt, đầu vào và tiêu chí chấm điểm nhất quán trong quá trình đánh giá.
Gemini 4 Hydrogen API Limitations
Hướng dẫn nhà phát triển Hydrogen mô tả các hạn chế ảnh hưởng tới client hiện có. Xử lý chúng trong việc xây dựng yêu cầu thay vì thử lại payload bị từ chối.
- Unsupported fields: loại bỏ thinkingBudget, thinkingLevel đặt thành MINIMAL, frequencyPenalty, presencePenalty và candidateCount lớn hơn một.
- Ignored sampling settings: temperature, topP và topK tùy chỉnh không điều khiển output của Hydrogen.
- Caching: cachedContent rõ ràng không được hỗ trợ. Prompt tiền tố ổn định có thể dùng cache ngầm, nhưng điều đó không thiết lập mức giảm giá cache riêng cho cổng.
- Long output: client mẫu trong hướng dẫn này chỉ triển khai yêu cầu đồng bộ. Nó không bao phủ decode dài nền hoặc workflow tiếp tục riêng của nhà cung cấp.
- Conversation changes: sửa các prompt trước đó hoặc định nghĩa công cụ có thể làm vô hiệu trạng thái suy luận. Bảo toàn tiền tố, hoặc triển khai hành vi không khớp tiền tố được tài liệu cho tuyến đã chọn.
Common setup checks
| Symptom | First check |
|---|---|
| 401 or 403 | Xác nhận thông tin xác thực thuộc về endpoint và có quyền truy cập mô hình đã chọn. |
| 400 | Đọc thân lỗi; kiểm tra các trường không được hỗ trợ, JSON sai định dạng và metadata hội thoại. |
| No visible text | Kiểm tra promptFeedback, các phần candidate và finishReason; phản hồi có thể bị chặn, chưa đầy đủ hoặc đang yêu cầu công cụ. |
| MAX_TOKENS | Xem văn bản là có thể chưa đầy đủ và xem lại ngân sách đầu ra trước khi chấp nhận. |
| File request rejected | Xác minh MIME type thực tế và giới hạn payload của tuyến đã chọn. |
Với lỗi bất ngờ, ghi lại mô hình, tuyến, trạng thái, thời điểm và ID yêu cầu khi có. Giữ khóa API và nội dung tệp nhạy cảm ngoài các log thường lệ.
FAQ
How should I retry Gemini 4 Hydrogen API rate-limit errors?
Với HTTP 429, giảm mức đồng thời và thử lại với backoff lũy thừa và jitter, kèm số lần thử tối đa cố định. Giữ ID yêu cầu khi cổng cung cấp. Không thử lại yêu cầu không hợp lệ hoặc lỗi xác thực mà không thay đổi; hướng dẫn lỗi và retry của CometAPI phân biệt chúng với lỗi tạm thời. Timeout có thể xảy ra sau khi xử lý đã bắt đầu, nên bảo vệ mọi hành động phía ứng dụng khỏi thực thi trùng lặp.
Can I call Gemini 4 Hydrogen API directly from a web app?
Chuyển hướng yêu cầu qua backend của bạn. Khóa nhúng trong JavaScript frontend có thể bị khách truy cập trích xuất, ngay cả khi mã được bundle hoặc minify. Để backend xác thực người dùng, áp dụng hạn mức sử dụng và gửi yêu cầu mô hình. Với streaming, chuyển tiếp phản hồi từng phần tới trình duyệt mà không để lộ khóa API thượng nguồn.
How should I handle an interrupted Gemini 4 Hydrogen stream?
Coi văn bản đã nhận là kết quả một phần cho đến khi phản hồi hoàn tất. Một yêu cầu mới bắt đầu sinh mới; nó không tự động tiếp tục stream bị ngắt ở cùng token. Giữ đầu ra một phần tách biệt với câu trả lời thử lại, và không thực thi hành động từ JSON chưa hoàn thành hoặc tham số công cụ chưa xong. Cung cấp thao tác retry hiển thị thay vì nối thầm lặng hai lần sinh.
Conclusion
Dùng một nhiệm vụ đại diện làm kiểm tra chấp nhận đầu tiên: yêu cầu phải thành công, ứng dụng phải trích xuất kết quả như dự định và mức dùng token ghi nhận phải phù hợp với ngân sách của bạn. Thêm từng tính năng một và giữ bài kiểm tra đó trong bộ kiểm thử tích hợp. Một client nhỏ, dễ quan sát sẽ dễ mở rộng hơn một workflow lớn mà lỗi khó truy vết.

