Cách Sử Dụng API Gemini 4 Hydrogen

API Gemini 4 Hydrogen sử dụng model ID gemini-4-hydrogen. Bạn gọi nó bằng yêu cầu POST tới https://generativelanguage.googleapis.com/v1beta/interactions, với khóa API trong header x-goog-api-key, và model cùng input trong phần thân JSON. Mô hình chạy được trên gói miễn phí lẫn gói trả phí ($1.50 đầu vào, $7.50 đầu ra cho mỗi 1 triệu token) và mặc định ở mức tư duy high.

Bài hướng dẫn này đi qua toàn bộ quy trình: lấy khóa, gửi yêu cầu đầu tiên, mức tư duy, xử lý PDF, function calling, streaming và xử lý lỗi. Mọi tên trường đều lấy từ tài liệu chính thức của Google.

Bạn cần chuẩn bị gì trước khi gọi API Gemini 4 Hydrogen lần đầu?

Bạn cần một khóa API Gemini, model ID gemini-4-hydrogen và endpoint Interactions. Google phát hành Hydrogen vào ngày 12 tháng 11 năm 2026, như mô hình Gemini 4 tốc độ cao bên cạnh Carbon và Argon (Gemini 4 Hydrogen là gì).

Tài liệu của Google xếp generateContent là bản cũ (legacy), nên các ví dụ dưới đây dùng Interactions.

Làm thế nào để lấy khóa API Gemini cho Hydrogen?

Hydrogen có trên gói miễn phí, nên bạn có thể bắt đầu mà không cần bật thanh toán:

1. Mở trang API keys trong Google AI Studio.
2. Nhấn Create API key. Khóa mới tạo trong AI Studio là khóa ủy quyền, gắn với một service account.
3. Xuất khóa: export GEMINI_API_KEY="YOUR_API_KEY". Các SDK đọc GEMINI_API_KEY hoặc GOOGLE_API_KEY; nếu cả hai đều được đặt, GOOGLE_API_KEY sẽ được ưu tiên.
4. Cloud project được tạo ngoài AI Studio có thể cần xác minh project trước khi gói miễn phí hoạt động.

Google công bố các con số của gói miễn phí trên trang giới hạn tốc độ, chứ không nằm trong tài liệu ra mắt. Bài hướng dẫn dùng Gemini 4 Hydrogen miễn phí của chúng tôi trình bày chi tiết những gì bạn được ở mức $0.

Làm thế nào để gửi yêu cầu API Gemini 4 Hydrogen đầu tiên?

Gửi model và input tới endpoint Interactions. Hãy đặt tên mô hình vào một biến để việc đổi mô hình chỉ là thay đổi một dòng.

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

Cùng yêu cầu đó với 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)

Phản hồi chứa id, status và mảng steps. Văn bản nằm trong các bước model_output, phần suy luận nằm trong các bước thought, và output_text của SDK đã nối sẵn văn bản cho bạn. Đối tượng usage chứa total_input_tokens, total_thought_tokens, total_output_tokens và total_tokens.

Các đoạn mã trên dựa theo quickstart của Google. Chúng tôi chưa chạy chúng cho bài viết này (máy thử nghiệm không có khóa Gemini), nên hãy kiểm tra cấu trúc phản hồi với lần gọi đầu tiên của bạn.

Làm thế nào để đặt mức tư duy của Gemini 4 Hydrogen?

Đặt thinking_level bên trong generation_config. Hydrogen mặc định ở mức high, bổ sung mức mới xhigh, và từ chối minimal với thông báo lỗi.

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

Có hai quy tắc quan trọng. max_output_tokens giới hạn cả tư duy và đầu ra chung với nhau, nên một mức trần thấp từ trước (ví dụ 8.192) có thể cắt ngắn câu trả lời; Google khuyên nên nâng lên 65.536 và hạ mức tư thay vì hạ trần. Ngoài ra, token tư duy được tính theo giá đầu ra $7.50, nên xhigh tốn kém hơn ngay cả khi câu trả lời hiển thị có độ dài như nhau. Bài phân tích giá Gemini 4 Hydrogen tính chi tiết chi phí theo từng mức.

Google cũng cho biết máy chủ bỏ qua temperature, top_p và top_k trên Hydrogen, nên hãy bỏ chúng khỏi các yêu cầu của bạn.

Làm thế nào để gửi PDF tới Gemini 4 Hydrogen?

Thêm một mục document vào mảng input, cạnh một mục text chứa hướng dẫn của bạn. Với tệp nhỏ, hãy gửi PDF inline dưới dạng 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."}
    ]
  }'

Với tệp lớn hơn hoặc cần dùng lại qua nhiều lượt, hãy tải lên một lần bằng Files API (miễn phí, lưu 48 giờ) rồi truyền {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"} thay thế. Theo hướng dẫn xử lý tài liệu, PDF có thể lên tới 50 MB hoặc 1.000 trang, và mô hình đọc được cả biểu đồ, bảng và hình ảnh trong tài liệu, không chỉ phần văn bản.

Function calling hoạt động thế nào với Gemini 4 Hydrogen?

Khai báo hàm của bạn trong tools. Mô hình không tự chạy gì cả; nó trả về một bước function_call, mã của bạn chạy hàm đó, rồi bạn gửi lại một function_result. Đây là bước một, theo hướng dẫn function calling của 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"]
      }
    }]
  }'

Tìm bước có type là function_call và đọc name, arguments và id của nó. Chạy hàm của bạn, rồi gửi kết quả trở lại trong cùng phiên:

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 giữ trạng thái hội thoại và tư duy phía Google, nên bạn không cần gửi lại lịch sử. Một cảnh báo từ ghi chú chuyển đổi của Google: nhắc mô hình in ra JSON "tool call" thô khi không khai báo công cụ nào có thể trả về MALFORMED_FUNCTION_CALL. Hãy khai báo công cụ theo cách chính thống hoặc dùng structured outputs.

Làm thế nào để stream phản hồi từ Gemini 4 Hydrogen?

Thêm "stream": true vào phần thân yêu cầu. API sẽ trả lời bằng 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
  }'

Theo hướng dẫn streaming của Google, bạn nhận interaction.created, rồi step.start, step.delta và step.stop cho từng bước (thought, sau đó model_output), cuối cùng là interaction.completed cùng usage cuối. Hãy nối delta.text từ các bước model_output để dựng câu trả lời. Streaming không nâng giới hạn: mỗi lần gọi vẫn dừng ở 65.536 token. Với đầu ra dài hơn, đặt "background": true với max_output_tokens trên 65.536 và thăm dò GET /v1beta/interactions/{id} cho tới khi status rời khỏi in_progress hoặc queued.

Làm thế nào để xử lý lỗi API Gemini 4 Hydrogen?

Lỗi không streaming được trả về dưới dạng mã trạng thái HTTP kèm đối tượng error chứa code và message. Trong stream, bạn nhận một sự kiện error với cùng các trường đó. Các mã bạn hay gặp nhất, theo trang lỗi API của Google:

Hướng dẫn khắc phục sự cố của Google khuyên chỉ nên thử lại với 429, 408 và 5xx, dùng exponential backoff cộng jitter và giới hạn số lần thử, và tuyệt đối không thử lại với 400, 402 hay 403. Python SDK đã tự động thử lại các lỗi tạm thời tối đa bốn lần.

Để coding agent của bạn kiểm thử API Hydrogen với Apidog CLI

Thay vì đọc JSON sau mỗi lần thay đổi prompt hay mức tư duy, hãy để coding agent của bạn (Claude Code, Codex, Cursor) dựng một bộ kiểm thử có thể lặp lại và chạy nó bằng Apidog CLI.

Cài đặt một lần:

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

Sau đó chỉ đưa cho agent một 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 kiểm tra từng payload với schema của CLI trước khi viết bất cứ thứ gì:

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

Hai lần chạy trên so sánh số token tư duy cho cùng một prompt — con số直接影响 hóa đơn của bạn. Đổi -r cli,json thành -r junit và lần chạy tương tự sẽ chạy được trong CI; hướng dẫn CI/CD với Apidog CLI trình bày pipeline và Apidog CLI trong Claude Code hướng dẫn cấu hình agent. Gói Free của Apidog hỗ trợ tới 4 người dùng.

Câu hỏi thường gặp

Model ID của Gemini 4 Hydrogen là gì? gemini-4-hydrogen. Nó hoạt động với cả Interactions API và generateContent.

API Gemini 4 Hydrogen có miễn phí không? Có, trong giới hạn nhất định. Google liệt kê Hydrogen trên gói miễn phí của Gemini API và AI Studio, với giới hạn tốc độ. Sử dụng trả phí có giá $1.50 mỗi 1 triệu token đầu vào và $7.50 mỗi 1 triệu token đầu ra.

Làm thế nào để chuyển từ Gemini 3.8 Flash? Đổi chuỗi tên mô hình, nâng các mức trần max_output_tokens thấp, bỏ temperature, top_p, top_k và explicit caching (cachedContents), và thay tư duy minimal bằng low hoặc medium.

Hydrogen có hỗ trợ context caching không? Chỉ có implicit caching. Nó chạy mặc định với các prompt từ 4.096 token trở lên và giảm 95% chi phí cho các lượt truy cập cache. Explicit caching không được hỗ trợ.

Hydrogen khác Gemini 4 Argon thế nào trong API? Cùng schema yêu cầu. Hydrogen mặc định ở high và bổ sung xhigh, còn Argon mặc định ở medium. Xem hướng dẫn Gemini 4 Argon API, hướng dẫn Gemini 4 Carbon API và Gemini 4 Hydrogen Orchestrator để biết cách ghép các mô hình.