重點摘要
Gemini 4 Hydrogen API 可透過 Google 的 Gemini API 與 CometAPI 等支援的第三方閘道使用。先選擇路徑:若需要供應商特有功能與帳戶控管,用 Google;若想要統一的模型閘道或沿用與 OpenAI 相容的用戶端,用 CometAPI。先從小型文字請求開始,再加入串流、多輪對話歷史、檔案與工具。
你需要 Python 3.10 或更高版本、所選路徑的金鑰,以及對 gemini-4-hydrogen 的存取權。選用的 JavaScript 範例需 Node.js 22 或更高版本。整個教學過程中請將憑證保存在伺服器端環境。
關鍵重點
- 使用
gemini-4-hydrogen作為 Gemini 4 Hydrogen API 的模型 ID。 - Google 與 CometAPI 的憑證與計費相互獨立。請將金鑰與你選擇的端點相匹配。
- 先使用原生的 GenerateContent;當你需要配合既有的聊天用戶端時,再使用 CometAPI 的 OpenAI 相容介面。
- 在多輪歷史中保留完整模型回應(包括簽名),然後再返回後續回應或工具結果。
- 在選擇路徑時比較實際的 token 使用量與已完成的任務;標準的 token 價例見定價章節。
什麼是 Gemini 4 Hydrogen API?
Google 於 2026 年 11 月 12 日推出 Hydrogen。該 API 接受提示與受支援的檔案,然後回傳產生的文字,或在使用工具時回傳由你的應用程式處理的結構化函式呼叫。你不需要自行託管模型。
先從純文字請求開始,並在加入工具或檔案前,確認回傳文字、結束原因與 token 使用量。完成後再加入對話狀態或唯讀的商務工具,而不是一次性建立整個工作流程。
Gemini 4 Hydrogen API 規格
| 規格 | Google 文件記載的模型能力 |
|---|---|
| 模型 ID | gemini-4-hydrogen |
| 輸入 | 文字、影像、音訊、影片,以及受支援的文件 |
| 輸出 | 文字;使用工具時包含結構化的函式呼叫部分 |
| 統一的上下文預算 | 輸入與輸出合計 1,048,576 個 token |
| 單次前景輸出片段 | 最多 65,536 個 token,包含推理與函式呼叫 |
| 應用程式功能 | 思考層級控制、結構化輸出與函式呼叫 |
以上為模型能力,並不保證每個閘道都會開放所有供應商特性。下列範例使用標準請求欄位與短前景輸出。
Google 官方 API 與 CometAPI
兩條路徑都支援 Gemini 請求,但使用不同的端點、憑證與計費系統。若需要供應商特有功能,請用 Google;若需要統一的模型閘道或既有的相容用戶端,請用 CometAPI。
| 決策 | Google Gemini Developer API | CometAPI 的 Gemini 整合 |
|---|---|---|
| 原生 API 主機 | generativelanguage.googleapis.com | api.cometapi.com |
| 本指南中的 API 金鑰 | GEMINI_API_KEY | COMETAPI_KEY |
| 帳戶與計費 | 由 Google 管理 | 由 CometAPI 管理 |
| 最佳起點 | 供應商特有功能與帳戶控管 | 統一的模型存取或既有與 OpenAI 相容的用戶端 |
在比較兩條路徑時,保持相同的提示與輸出預算,以便比較結果更有意義。JavaScript 與 OpenAI 相容替代範例會明確設定為 CometAPI。
如何逐步使用 Gemini 4 Hydrogen API?
步驟 1:建立 API 金鑰
對於 CometAPI,建立帳戶並在 API 代幣主控台 產生金鑰。若要直接使用 Google,請在 Google AI Studio 建立 Gemini API 金鑰。確認模型存取權與所選帳戶的計費或可用配額。
請安全保存金鑰。CometAPI 的金鑰無法用於 Google 的端點驗證,Google 的金鑰也無法用於 CometAPI 的請求。
在 Bash 中設定你選擇的路徑所需的金鑰;你只需要以下其中一行。
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
在 Windows 的 PowerShell 中設定相對應的金鑰。
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
步驟 2:使用 cURL 發送第一個請求
透過 CometAPI 從 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"
}
}
}'
或使用 Google API 金鑰直接向 Google 發送相同的原生請求。
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"
}
}
}'
請求成功後,請驗證三個欄位:candidates[0].content.parts(可見文字)、finishReason(完成狀態)與 usageMetadata(token 使用量)。在加入更多應用程式碼之前先修正驗證或請求錯誤。
步驟 3:設定 Python 用戶端並發送請求
安裝 Python 範例所需的套件。
python -m pip install requests openai
將以下輔助程式儲存為 hydrogen_client.py。將 PROVIDER 保持為 cometapi 以使用 CometAPI,或設為 google 以直接存取 Gemini Developer API。後續原生範例會匯入此檔案,因此會沿用所選路徑。
設定所選端點,並定義可重用的請求與文字輔助工具。
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
將下列內容儲存為 hydrogen.py(與輔助程式放在同一資料夾)。它會列印答案、完成原因與使用量,方便你判斷答案是否完整,或是因達到 token 上限而中止。
使用已設定的供應商發送一個文字請求。
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", {}))
在你已設定所選 API 金鑰的終端機中執行該指令碼。
python hydrogen.py
閱讀答案後,檢查 finishReason 以了解生成為何停止。在 usageMetadata 中查看此請求使用了多少 token。若為 MAX_TOKENS,即使 HTTP 請求成功,回應也可能不完整。
使用 JavaScript 或與 OpenAI 相容的用戶端
選擇符合你應用程式的範例。Node.js 範例送出原生 Gemini 請求。若你的應用程式已使用 OpenAI SDK,請跳到下方的 Python 範例。
使用 Node.js 的 JavaScript
將以下內容儲存為 hydrogen.js,並執行 node hydrogen.js。它會送出相同的原生請求結構,並擷取所有可見文字部分。
從 Node.js 發送原生的 GenerateContent 請求。
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);
使用 OpenAI SDK 的 Python
若你的應用程式已使用 OpenAI SDK,CometAPI 亦提供 POST /v1/chat/completions。最簡單的遷移方式是更改 API 金鑰、基底 URL 與模型 ID。將此路徑用於常見的聊天工作流程;當你需要 Gemini 特有欄位時,請改用 Gemini 原生端點。
透過 CometAPI 建立一個 Chat Completions 請求。
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)
原生範例使用 contents 與 generationConfig;Chat Completions 則使用 messages 與其特定請求欄位。請保持每個請求使用單一格式,而不要將原生欄位複製到不接受這些欄位的 SDK 呼叫中。
進階 Gemini 4 Hydrogen API 功能
以下範例會重複使用「設定」章節中的 hydrogen_client.py,因此會依據你在 PROVIDER 中選擇的供應商運作。下方的串流範例使用 CometAPI 的 Chat Completions 客戶端,適合既有與 OpenAI 相容的應用程式。
設定推理與結構化輸出
使用 generationConfig 設定 thinkingConfig.thinkingLevel 為 LOW、MEDIUM、HIGH 或 XHIGH。選擇一個能同時容納推理與可見答案的輸出預算。當應用程式需要 JSON 時,請使用 responseMimeType 與 responseSchema,而非只依賴自然語言格式指示。
為原生請求設定輸出預算與推理層級。
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
透過 CometAPI 串流回應
串流會在答案逐步產生時即時返回,而非等待完整答案。此功能適用於聊天介面、程式輔助,以及重視感知延遲的應用程式。
CometAPI 文件說明了以 stream=true 串流 Chat Completions(streaming Chat Completions with stream=true)。此 Python 範例會處理在串流回應中可能出現的無 choices 區塊。
透過與 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()
對於原生用戶端,CometAPI 文件說明了以 Server-Sent Events 串流的 streamGenerateContent(streamGenerateContent with Server-Sent Events)。該路徑返回的是 GenerateContent 回應物件,而非 Chat Completions 的增量。請讓剖析器與路徑保持一致;原生 Gemini 端點與與 OpenAI 相容閘道的串流行為可能不同。在遷移既有串流用戶端前,請先測試你的應用實際使用的 Hydrogen 路徑。
保留多輪對話歷史
在下一個請求中傳送先前的使用者與模型回合。保留模型的完整 content 物件,而非從可見文字重建;這能在下一回合保留回傳的中繼資料。將此範例儲存為 hydrogen_history.py(與共用輔助程式放在一起)。
在保留第一個模型回應完整性的前提下,送出兩個相關的請求。
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"))
執行 python hydrogen_history.py。第二個答案應該會延續第一回合的設計。此範例中請保持較早的對話前綴不變;長時間運作的應用需另行規劃壓縮與上下文限制策略。
傳送影像與 PDF
Hydrogen 支援影像與文件理解。在 Gemini 原生請求格式中,將 inlineData 與文字指示一起加入。這適用於螢幕截圖分析、架構圖、掃描表單與報告萃取。
將此範例儲存為 analyze_file.py(與 hydrogen_client.py 同資料夾)。它會傳送一個本機影像或 PDF,因此你可以對兩種輸入重複使用相同程式碼。第一次請求請使用小檔案;Base64 會增加請求大小。
使用共用原生用戶端分析本機 PNG、JPEG 或 PDF。
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))
用你自己的文件或影像執行此檔案範例。
python analyze_file.py report.pdf
python analyze_file.py diagram.png
檔案位元組必須與宣告的 MIME 類型相符。更改副檔名不會轉換檔案格式。若上傳遭拒,請先檢查錯誤訊息中的大小或格式限制再重試;不要假設由 Google 託管的檔案 URI 能透過第三方閘道存取。
連接由應用程式控管的工具
函式呼叫可讓模型請求由你的應用程式執行的操作。模型會回傳結構化的函式呼叫;你的應用程式驗證參數、執行函式,並回送結果。
此範例使用一個小型、虛構的訂單資料庫。將其儲存為 order_agent.py(與共用用戶端同資料夾)。它實作完整往返、將迴圈上限設為四次請求,並在回合間保留完整的模型內容(包含任何回傳的簽名)。
針對本機示範資料庫執行一個有界的函式呼叫迴圈。
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.")
執行 python order_agent.py。最終答案應反映 DEMO-1001 的本機紀錄。在真實服務中,必須先授權使用者再存取訂單;模型選擇的訂單編號並不代表具備存取許可。
Gemini 4 Hydrogen API 的費用是多少?
以下費率以美元計,每百萬個 token,檢查日期為 2026 年 11 月 17 日。比較的是標準未快取的輸入與輸出,不包含批次、優先、快取輸入或另計費的工具使用。
| Token 類型 | Google 全域標準 | CometAPI 中的 Gemini 4 Hydrogen API |
|---|---|---|
| 輸入 token / 1M | $1.50 | $1.20 |
| 輸出 token / 1M | $7.50 | $6.00 |
若有 100,000 個輸入 token 與 10,000 個可計費輸出 token,CometAPI 的估算為 0.1 × $1.20 + 0.01 × $6.00 = $0.18。在 Google 列示的標準費率下,相同用量為 $0.225,差異為 20%。請將推理 token 計入輸出使用量,並在估算真實工作流程時檢查你帳戶的計費用量。
如何遷移到 Gemini 4 Hydrogen API?
從 Gemini 3.8 Flash 遷移時有哪些改變?
在更改模型 ID 之前,確認推理設定、上下文預算,以及你的用戶端每次請求所帶的對話歷史。
| 整合細節 | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| 預設思考層級 | MEDIUM | HIGH |
| 上下文計算 | 輸入與輸出分開限制 | 輸入與輸出共用一個預算 |
| 多輪狀態 | 檢視既有用戶端的歷史處理 | 保留完整的模型部分與簽名;前綴編修需要特別處理 |
當你的應用仰賴預設值、會壓縮歷史或執行多次工具回合時,已文件化的移轉變更 尤其重要。請明確設定推理,並在更換生產模型之前,先以短小的既有工作流程進行測試。
更新既有整合
建立一個使用新模型 ID 的測試組態,同時保持其金鑰與端點相對應。使用兩種組態執行相同的代表性工作流程,以便比較其行為。
- 送出新的文字請求,並驗證其完成原因與 token 使用量。
- 使用完整的模型回應物件重播多輪任務與工具往返。
- 在比較請求結果之前,移除限制章節中列出的不相容控管。
- 在新的對話中測試你的回退路徑;不要假定其他模型能接受 Hydrogen 儲存的推理中繼資料。
判斷遷移是否有助於你的工作負載
當新組態能在可接受的每完成任務成本下,達到任務的品質與延遲目標時再採用。若既有用戶端已達成這些目標,請先以限量試點建立效益,再遷移所有請求。評估期間請保持提示、輸入與評分標準一致。
Gemini 4 Hydrogen API 限制
Hydrogen 開發人員指南 描述了會影響既有用戶端的限制。請在建構請求時處理這些限制,而非對相同被拒的負載重試。
- 不支援的欄位:移除 thinkingBudget、將 thinkingLevel 設為 MINIMAL、frequencyPenalty、presencePenalty,以及大於 1 的 candidateCount。
- 忽略的取樣設定:自訂 temperature、topP 與 topK 不會控制 Hydrogen 的輸出。
- 快取:不支援明確的 cachedContent。穩定的提示前綴可使用隱式快取,但這不代表可取得特定閘道的快取折扣。
- 長輸出:本指南中的範例用戶端僅實作同步請求。不涵蓋背景長解碼或供應商特定的續傳工作流程。
- 對話變更:修改較早的提示或工具定義可能會使推理狀態失效。請保留前綴,或為所選路徑實作文件化的前綴不相符行為。
常見設定檢查
| 症狀 | 首要檢查 |
|---|---|
| 401 或 403 | 確認該憑證屬於該端點,且對所選模型具備存取權。 |
| 400 | 閱讀錯誤本文;檢查不支援欄位、格式不正確的 JSON 與對話中繼資料。 |
| 沒有可見文字 | 檢查 promptFeedback、candidate 的 parts 與 finishReason;回應可能被封鎖、不完整,或正在要求使用工具。 |
| MAX_TOKENS | 將文字視為可能不完整,並在接受前檢視輸出預算。 |
| 檔案請求遭拒 | 驗證實際 MIME 類型與所選路徑的負載大小上限。 |
對於非預期失敗,請記錄模型、路徑、狀態、時間戳,以及可用時的請求 ID。請勿將 API 金鑰與敏感檔案內容寫入一般日誌。
常見問題
我應該如何重試 Gemini 4 Hydrogen API 的速率限制錯誤?
對於 HTTP 429,降低並行度並以指數退避與抖動進行重試,且設定固定的最大嘗試次數。保留閘道提供的請求 ID。請勿對無效請求或驗證失敗進行不變更的重試;CometAPI 的錯誤與重試指南 區分了這些與暫時性失敗。逾時可能在處理已開始後才發生,因此請保護任何由應用程式端執行的動作,避免重複執行。
我可以直接從網頁應用呼叫 Gemini 4 Hydrogen API 嗎?
請透過你自己的後端路由請求。嵌入在前端 JavaScript 的金鑰可能會被訪客擷取,即使代碼已打包或最小化。請讓後端驗證使用者、套用使用限制並發送模型請求。若需串流,請將增量回應轉發到瀏覽器而不暴露上游 API 金鑰。
我該如何處理中斷的 Gemini 4 Hydrogen 串流?
在回應完成前,將已接收文字視為部分結果。新請求會開始新的生成;不會自動從中斷的串流同一個 token 位置繼續。請將部分輸出與重試答案分開,且不要從不完整的 JSON 或未完成的工具參數執行動作。提供可見的重試動作,而非悄悄將兩次生成的內容串接。
結論
請以具代表性的任務作為首次驗收檢查:請求應成功、應用程式能擷取預期結果,且記錄的 token 使用量符合你的預算。一次加入一項功能,並將該檢查納入你的整合測試。小而可觀察的用戶端比起大型而難以排查失敗的工作流程更容易擴展。

