Gemini 4 Hydrogen APIの使い方：Google・Ofoxで初回リクエスト

Googleに直接リクエストする場合は、gemini-4-hydrogenとGoogleのAPIキーを使います。OfoxのChat Completions経由では、google/gemini-4-hydrogenとOfoxのキーを使います。エンドポイント、認証情報、レスポンスの読み取り方を、選んだ接続方法にそろえてください。 プロトコルを変更するときは、モデル名を変えるだけでは動きません。

Googleは2026年11月12日に開発者向けにHydrogenを公開しました。API利用が有料枠に限られるCarbonと異なり、HydrogenはGoogleの無料枠と有料枠に対応します。ただし、無料で使えるかはプロジェクトの利用資格、認証状態、有効な上限に左右されます。本記事は2026年11月13日時点のドキュメントとOfoxのカタログを確認し、接続方法の選択から1件のテキストレスポンスの保存・検証までを説明します。

本記事はOfoxが公開しています。リクエスト形式の確認と合成データによる検証プログラムのテストを行いましたが、有料のHydrogen推論は実行しておらず、速度や回答品質も測定していません。掲載コードは読者が実行できるサンプルであり、特定アカウントで実際のAPI呼び出しが成功したという報告ではありません。モデルを選ぶ段階なら、Carbon・Hydrogen・Argonの比較を参照してください。リンク先のGoogle公式資料は英語です。

キーを作る前に接続方法を選ぶ

以下の2つの例は、別のサービスを介して同じモデル系列にアクセスします。利用するアカウントに合う方を実行してください。両方を実行する必要はありません。

Googleは新規連携にInteractionsを推奨しており、GenerateContentも引き続きサポートしています。Ofoxの現在の公開カタログにはHydrogenのOpenAI・Geminiプロトコル対応と、OpenAI側の/v1/chat/completionsが明記されています。本記事はこの記載された経路を使います。GoogleのInteractionsサンプルのBase URLをOfoxに変更するだけで動く、という意味ではありません。

OfoxにはGeminiネイティブプロトコルのドキュメントもありますが、リクエストの仕様は別です。共通ドキュメントに明示的キャッシュなどの機能が載っていても、すべてのGeminiモデルが使えるとは限りません。ツール、ストリーミング、マルチモーダル入力を追加する前に、使うプロトコルを決めましょう。

2026年11月13日に取得した公式発表の画面です。公開情報を示すもので、API実行結果や性能測定ではありません。英語の原文。

Googleプロジェクトと無料枠の認証を確認する

Googleの例を使う場合は、AI StudioのAPIキーページを開き、リクエストをどのプロジェクトに帰属させるか確認します。新規ユーザーにはデフォルトのプロジェクトが作成される場合があります。既存のCloudプロジェクトはAI Studioへのインポートが必要な場合があります。対象プロジェクトのキーを作成または選択し、利用枠と残りの割り当てを確認してください。別プロジェクトのキーでも認証は成功することがありますが、消費する枠は異なります。

Hydrogenに無料枠があっても、新しく作ったすべてのプロジェクトがすぐ使えるわけではありません。Googleのプロジェクト認証ガイドでは、追加プロジェクトやAI Studio外で作成したプロジェクトなどで認証が必要になる場合が示されています。対象のリクエストは403とFREE_TIER_VERIFICATION_REQUIREDを返します。

このエラーが出た場合は、次の手順で対応します。

1. エラー内の認証リンクを開くか、AI StudioのProjectsページで Verify project を選択します。プロジェクト番号がキーの所属先と一致することを確認します。
2. 対応する実機スマートフォンでGoogleのデバイス認証を進めます。プロジェクト権限が不足している場合は、管理者に認証を依頼してください。
3. 認証済みの表示を確認してから、下記の小さなリクエストを1回再実行します。

同じプロジェクトでキーを作り直しても、プロジェクト単位の認証要件は解除されません。有料の請求設定は費用を伴う別の選択肢であり、すべてのHydrogenユーザーに必須の初期操作ではありません。一般的な403を見ただけで請求設定を変更せず、具体的な理由を読んでください。

AI Studioで有効なレート制限を確認します。Googleの制限はキー単位ではなくプロジェクト単位です。リクエスト数とトークン数の上限は別々に達することがあります。同じプロジェクトのキーを2つにしても、独立した枠が2つになるわけではありません。本記事では全アカウント共通の無料RPMを提示しません。対象プロジェクトとモデルに表示される値を使ってください。

キーはサーバー側の環境変数GEMINI_API_KEYに保存するか、デプロイ環境のシークレット管理から読み込みます。ブラウザーのコードやリポジトリには含めないでください。現在のキーの公式説明では、認可キーと標準キーを区別しています。AI Studioで新規作成するキーはデフォルトで認可キーです。無制限の標準キーは拒否されますが、制限を明示した標準キーは引き続き利用できます。

下記プログラムはGEMINI_API_KEYを明示的に読みます。両方の変数があるとGOOGLE_API_KEYが優先されるSDKの自動選択を避けるためです。macOS/Linuxではexport GEMINI_API_KEY="YOUR_GOOGLE_KEY"、PowerShellでは$env:GEMINI_API_KEY="YOUR_GOOGLE_KEY"を使います。自分の端末で値を置き換え、共有のコマンド履歴にキーを残さないようにしてください。設定とプログラム実行は同じターミナルセッション内で行います。

PythonでGoogleにリクエストする

現在のSDKにはPython 3.11以降を使い、分離した環境を作ります。ローカル確認ではPython 3.11とgoogle-genai 3.3.0を使いました。このパッケージの最低要件はPython 3.11です。古いgoogle-generativeaiではなく、google-genaiを使用します。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

Windows PowerShellでは.venv\Scripts\Activate.ps1で環境を有効化します。指定した最低バージョンはPythonのフォアグラウンド継続処理に対応していますが、今回の短いテストはHydrogenの1回分の応答予算内に収めます。次のコードをhydrogen_google.pyとして保存してください。

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended Google project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give exactly three short bullet points about avoiding duplicate API retries.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 65536,
    },
)
Path("hydrogen-google.json").write_text(
    json.dumps(interaction.model_dump(mode="json"), indent=2),
    encoding="utf-8",
)
print("Saved hydrogen-google.json")
print("Interaction:", interaction.id)
print("Status:", interaction.status)

python hydrogen_google.pyを実行します。実際にキーの所属プロジェクトへリクエストするため、有料枠の利用は課金対象です。使えるテキストが得られなかった場合もレスポンスを保存します。成功と判断する前に、後述の検証プログラムを実行してください。

プロンプトは短く、思考レベルはlowです。65,536は思考と可視出力を合わせた上限であり、その量の生成指示でも、必ず消費・請求される量でもありません。上限が小さすぎると、思考の後にテキストを出す余地がなくなることがあります。接続確認では入力を短く保ち、上限ではなく実際のusageを確認します。

store=Falseは、対話状態を保存しない単発の呼び出しにする設定です。バックグラウンドジョブやprevious_interaction_idを使う会話に、そのまま流用しないでください。プロバイダーのあらゆるログを残さないという保証でもありません。保存仕様はInteractionsの概要を確認してください。

OfoxのChat Completionsでリクエストする

OfoxではAPIキーの設定・利用方法に沿ってキーを作成または選択し、サーバーまたはローカル端末のOFOX_API_KEYに設定します。macOS/Linuxはexport OFOX_API_KEY="YOUR_OFOX_KEY"、PowerShellは$env:OFOX_API_KEY="YOUR_OFOX_KEY"で、値はローカルで置き換えます。実行前に残高と現在のHydrogenモデルページ（英語）を確認してください。Googleの無料枠でOfoxのリクエストを支払うことはできず、Ofox残高でGoogleのエンドポイントを利用することもできません。

今回取得した公開カタログの完全なスナップショットには133モデルがあり、google/gemini-4-hydrogenが掲載されていました。確認できるのは取得日時点の登録と対応プロトコルです。推論成功の記録ではなく、すべてのアカウント、プロバイダー、将来の構成を保証するものでもありません。

以下をhydrogen-ofox-request.jsonとして保存します。

{
  "model": "google/gemini-4-hydrogen",
  "messages": [
    {
      "role": "user",
      "content": "Give exactly three short bullet points about avoiding duplicate API retries."
    }
  ],
  "max_tokens": 65536,
  "stream": false
}

ターミナルからcurlで送信します。

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://api.ofox.ai/v1/chat/completions' \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-ofox-request.json \
  --output hydrogen-ofox.json

このリクエストはOfoxのChat Completionsエンドポイント・パラメーター仕様に従います。後からOpenAI互換SDKを設定する場合、/v1を重複させないでください。Base URLはhttps://api.ofox.ai/v1で、RESTの完全なURLにはさらに/chat/completionsが付きます。

例ではtemperature、top_p、プロバイダー固有の思考拡張を意図的に省いています。Googleネイティブのgeneration_configはOpenAI Chat Completionsのパラメーターではありません。そのまま貼り付けてゲートウェイが転送すると考えないでください。Ofoxの特定の経路で思考を設定する際は、その経路で文書化されたパラメーター対応を確認します。後述のネイティブ4段階の表は、任意の互換フィールドが有効だという証拠ではありません。

curlの終了コードが0以外なら、HTTPまたは通信処理が失敗しています。保存したエラー本文を確認し、ログを共有する前にキーを除去してください。タイムアウトはクライアントの待機上限であり、応答速度の予測値ではありません。タイムアウトしても上流処理が停止したとは限らないため、直後に有料リクエストを連続して送り直さないようにします。

使用したプロトコルに合わせてレスポンスを検証する

HTTP 200でも、未完了の対話、ツール呼び出し、使えるテキストがない結果の場合があります。逆に、別APIのフィールドを読めば、正常な応答も空に見えます。Google SDKにはinteraction.output_textという便利なプロパティがありますが、保存する対話リソースはstepsを使います。Chat Completionsはchoicesを使います。

次の検証コード全体をcheck_hydrogen.pyとして保存します。ローカルファイルだけを読み、ネットワークアクセスや推論の再送信は行いません。

import json
import sys
from pathlib import Path

def validate(payload, route):
    if "error" in payload:
        raise ValueError("API error: " + json.dumps(payload["error"]))
    if route == "google":
        if payload.get("status") != "completed":
            raise ValueError("Interaction is not completed: " + str(payload.get("status")))
        text = "".join(
            part.get("text", "")
            for step in payload.get("steps", [])
            if step.get("type") == "model_output"
            for part in step.get("content", [])
            if part.get("type") == "text"
        )
    elif route == "ofox":
        choices = payload.get("choices") or []
        if not choices:
            raise ValueError("No Chat Completions choices in response")
        choice = choices[0]
        if choice.get("finish_reason") != "stop":
            raise ValueError("Text did not finish normally: " + str(choice.get("finish_reason")))
        text = (choice.get("message") or {}).get("content") or ""
    else:
        raise ValueError("Route must be google or ofox")
    if not isinstance(text, str) or not text.strip():
        raise ValueError("No usable text; inspect the saved JSON")
    return text

def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python check_hydrogen.py google|ofox response.json")
    payload = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
    try:
        text = validate(payload, sys.argv[1])
    except ValueError as exc:
        raise SystemExit(str(exc))
    print("Response ID:", payload.get("id"))
    print("Usage:", json.dumps(payload.get("usage")))
    print(text)

if __name__ == "__main__":
    main()

Googleはpython check_hydrogen.py google hydrogen-google.json、Ofoxはpython check_hydrogen.py ofox hydrogen-ofox.jsonで確認します。合格時はレスポンスID、usage、可視テキストを表示します。さらに本文を読み、短く関連性のある箇条書きが3つあることを確認してください。このコードが検証するのはプロトコル上の完了と空でないテキストであり、助言の事実上の正しさではありません。

ローカルでは、完了、空テキスト、エラー、未完了、ツール応答の合成データを使用し、Googleの複数出力ステップに分かれたテキストも確認しました。これで分かるのは検証ロジックの動作であり、実環境の認証、割り当て、遅延、回答品質ではありません。ツールを使うアプリではtool_callsが正しい終了理由になり得ますが、今回は最終テキストが必要なので不合格になります。

思考レベルと出力長を区別する

HydrogenのネイティブAPIは4段階の思考レベルを持ち、デフォルトはhighです。CarbonとArgonのデフォルトはmediumです。思考の公式ドキュメントが説明するのは推論にかける労力であり、固定の文字数設定ではありません。

これはテスト開始時の選択肢で、Ofoxのベンチマーク結果ではありません。比較時は入力と合格条件をそろえ、正確なモデル、レベル、状態、所要時間、usage、合否理由を記録します。設定は1つずつ変えてください。見える回答が短くても、思考トークンが少ないとは限りません。

Hydrogenは入力・思考・出力で1,048,576トークンを共有します。入力100万に加えて回答100万が別枠であるわけではありません。同期処理の思考・出力の標準予算は65,536で、ストリーミングの有無にかかわらず1回の応答でこの上限に対応します。より長い出力には、Long Decodeで説明する継続またはバックグラウンド処理が必要です。

最初のテストで出力上限を100万にしないでください。後からバックグラウンド処理を使う場合はジョブIDを保存し、待機中と終了状態を明示的に処理します。background=trueだけでは標準の出力上限は増えません。本記事は短いフォアグラウンド呼び出しの検証であり、長時間ジョブを管理する完全な実装ではありません。

Hydrogenの出力はテキストです。モデルカードには画像、動画、音声、PDFの入力が記載されていますが、ネイティブ画像生成、音声生成、Live API対応は記載されていません。画像を読み取って分析する能力と、新しい画像を生成する能力は別です。まずテキストの基準動作を確認してから、対応する入力を1種類追加します。

失敗した箇所に絞って対処する

診断メモにはエンドポイント、モデル文字列、プロジェクトまたはアカウント、SDKバージョン、正確なエラーをまとめます。共有前に認証情報を削除してください。1つのフィールドが誤っているだけで環境全体を作り直す必要はありません。

Ofoxの応答にはOfoxのエラー処理ガイド、Googleの分類には公式トラブルシューティングを使います。Argon APIのエラー解説も、接続経路、割り当て、パースの問題を分ける参考になります。ただし、Argon専用の設定はHydrogenのデフォルトではありません。

ツールを追加する際は、選んだAPIのネイティブなツールフィールドで宣言します。プロンプトで独自形式の呼び出し文字列を出すよう頼むだけでは、実行側が認識するとは限りません。必要な会話履歴と署名を維持してください。署名が具体的な原因なら、thought signature欠落の対処を参照できます。

再現できる基準設定を残す

保存したレスポンス、正しい完了状態、指定どおりの3項目のテキスト、対象プロジェクト／アカウントのusage記録がそろえば、次の機能に進めます。モデル、接続方法、SDKバージョン、設定も記録し、キーは含めないでください。

次は実際のタスク用プロンプト、対応ファイル入力、ストリーミング、宣言済みツールのうち1つだけを追加します。新しい版で失敗したら元のテストを再実行し、接続自体の問題と追加機能の問題を切り分けます。

難しいタスクをCarbonに任せるべきかはGemini 4のモデル選択ガイドで比較できます。Carbon特有のアクセス条件と初回設定はCarbon API導入ガイドを参照してください。Hydrogenの成功はその連携の根拠になりますが、同じアカウント、パラメーター、パーサーを全サービスへ無変更で移せる証拠ではありません。