Gemini 4 Neon APIの使い方:モデルID、思考レベル、初回リクエストの確認方法
Gemini APIの有料プロジェクトからgemini-4-neonを呼び出す手順です。highとxhighの選び方、思考トークンとキャッシュトークンの読み方、Carbonと異なるエラーの対処法をまとめます。
Gemini 4 Neonを呼び出すには、有料ティアのGemini APIプロジェクトからmodel: "gemini-4-neon"を送ります。Neonには無料ティアがありません。デフォルトの思考レベルはhighで、low、medium、xhighも指定できます。入力・思考・出力は1つの1,048,576トークンのコンテキストウィンドウを共有します。GoogleのNeonガイドは新しいコードをInteractions APIで始める構成ですが、generateContentも使えます。 リクエストが成功したと言えるのは、interactionがcompletedになり(またはcandidateがSTOPで終了し)、表示可能なテキストがあり、課金対象(思考トークンを含む)が使用量の記録に表れているときです。
Googleは2026年11月18日にgemini-4-neonを一般提供(GA)として公開しました。本記事は2026年11月19日時点のGoogleドキュメントと照合しています。扱うのはNeon固有の部分です。プロジェクトの設定、APIキー、課金はもう1つの有料Gemini 4モデルと同じなので、Gemini 4 Carbon APIセットアップガイドで一度説明し、ここでは要点だけを示します。
本記事には2つの制約があります。
- NeonはOfoxでは利用できません。 2026年11月19日にOfoxのモデル一覧(
GET https://api.ofox.io/v1/models)を確認したところ、google/gemini-4-hydrogenとgoogle/gemini-4-argonは掲載されていましたが、Neonはありませんでした。https://ofox.io/models/google/gemini-4-neonは404を返しました。以下の例はすべてGoogleのネイティブエンドポイントと、GoogleのAPIキーを使います。このブログはOfoxが運営しています。 - Neonを実際に呼び出してはいません。 本記事の作成時にGoogleのキーがありませんでした。リクエスト本文は、Googleが公開している仕様(Neonガイド、Interactionsと
generateContentのリファレンス、思考・キャッシュ・長文出力のドキュメント)と照合しました。レスポンスチェッカーは、15件の合成レスポンスを使ってオフラインでテストしました。これで確認できるのはパーサーのロジックです。認証、レイテンシ、回答品質は確認できていません。
Gemini 4 Neon APIの主な仕様
以下の値はすべて、GoogleのWhat’s new in Gemini 4 Neonガイド、料金ページ、Neonモデルカード(いずれも英語)によるもので、2026年11月19日に確認しました。
| 項目 | Neonの値 |
|---|---|
| モデルID | gemini-4-neon(-previewサフィックスなし) |
| 利用条件 | Gemini APIの有料ティアのみ。Google AI ProとUltraプランではGoogle AI Studioでも利用可能 |
| API | Interactions API(Googleのクイックスタートで使用)とgenerateContent |
| 思考レベル | low、medium、high(デフォルト)、xhigh。minimalは拒否される |
| コンテキスト | 1,048,576トークン。入力・思考・出力で共有 |
| 同期出力 | 1ホップ(1回の生成単位)あたりのデフォルト値と上限が65,536トークン。ストリーミングと非ストリーミングで共通 |
| より長い出力 | バックグラウンド実行またはクライアント側の継続。上限は1Mから入力を引いた量 |
| 標準料金(100万トークンあたりUSD) | 入力$3.00、キャッシュ入力$0.15、出力(思考を含む)$15.00 |
| キャッシュ | 暗黙的キャッシュのみ。プロンプト4,096トークン以上で有効。明示的なcachedContentsは非対応 |
| サンプリング | temperature、top_p、top_kは範囲内なら無視され、範囲外なら400を返す |
| 知識のカットオフ | 2026年3月(モデルカード) |
Carbonには11月30日に終わる導入価格がありますが、Neonには導入価格がありません。思考レベル別のタスク単価は、Gemini 4 Neonの料金解説を参照してください。
CarbonやHydrogenのリクエストから何が変わるか
Googleは、他のGemini 4モデルからNeonへの切り替えについて「リクエストスキーマの変更は不要」としています。フィールドは同じで、変わるのはその値と周辺の制限です。すでにCarbonやHydrogenのセットアップガイドに沿って動くコードがある場合は、次の違いに注意してください。
| 項目 | Carbon | Hydrogen | Neon |
|---|---|---|---|
| モデルID | gemini-4-carbon | gemini-4-hydrogen | gemini-4-neon |
| 無料ティア | なし | あり | なし |
| デフォルトの思考レベル | medium | high | high |
xhigh | 非対応 | 対応 | 対応 |
| 非ストリーミングの1ホップ | 生のREST呼び出しで1ホップ32,768トークン | 65,536 | 65,536 |
| サンプリングパラメータ | 無視 | 範囲内は無視、範囲外は400 | 範囲内は無視、範囲外は400 |
| 標準料金(入力/出力) | 11月30日まで$2 / $10、以降$4 / $20 | $1.50 / $7.50 | $3 / $15で固定 |
出典:Carbon、Hydrogen、Neonの各「What’s new」ガイドとChoosing a modelページ(英語)。32,768と65,536のホップの比較は、GoogleのHydrogenガイドに記載されています。
実務上の影響は3つあります。
- Carbonから移行すると、1回あたりのデフォルトの支出が増えます。 Carbonのデフォルトは
medium、Neonはhighです。thinking_levelを一度も指定していないコードは、何も変えなくてもNeonではより多く思考します。コードレビューで挙動が分かるよう、レベルを明示的に指定してください。 - Hydrogenからの移行では、リクエストではなくキーが原因で失敗することがあります。 Hydrogenの連携は無料ティアのプロジェクトで動いている場合があり、同じキーではNeonに届きません。ペイロードをデバッグする前に、キーがどのプロジェクトに属しているか確認してください。
- Neon向けに書いたコードはCarbonで失敗することがあります。
xhighはNeonとHydrogenでは有効ですが、CarbonとArgonでは無効です。ステップごとにモデルを振り分ける場合は、思考レベルをグローバル定数にせず、ルーティングの一部として持たせてください。それぞれのモデルがどんなときに価格に見合うかは、NeonとCarbonの比較で扱っています。
ステップ1:キーが有料プロジェクトに属しているか確認する
Neonを使うには4つの条件がそろう必要があります。Gemini APIを使えるGoogleアカウント、Google AI Studio内のプロジェクト、そのプロジェクトに属するAPIキー、そして同じプロジェクトで有効になっている有料ティアの課金です。Googleの課金ガイドでは、無料ティアから有料ティアへの移行を、プロジェクトに請求先アカウントをリンクする操作として説明しています。各プロジェクトの課金ティアはProjectsページに表示されます。Google AI ProやUltraプランがあればAI StudioでNeonを使えますが、それをAPIキーのプロジェクトが有料ティアである証拠とみなさないでください。プロジェクトのティアはProjectsページで確認します。
詳しい手順(Cloudプロジェクトのインポート、キーの種類と制限、前払いと後払い)はCarbonセットアップガイドの最初のセクションにあり、Neonにもそのまま当てはまります。Googleの一次資料はAPIキーガイドと課金ガイド(いずれも英語)です。
キーは環境変数に入れ、値を表示せずに読み込まれているかだけを確認します。
export GEMINI_API_KEY="..." # シェルかシークレットマネージャーで設定し、絶対にコミットしない
python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'
Trueは値が存在することを示すだけです。プロジェクトがNeonに届くかどうかは、最初のリクエストで確かめます。
ステップ2:Interactions APIで最初のリクエストを送る
GoogleのNeonクイックスタートはInteractions APIを使っているので、新しいコードはここから始めます。現行のSDKをインストールしてください(パッケージ名はgoogle-genaiで、from google import genaiとしてインポートします。古いgoogle-generativeaiパッケージではありません)。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-genai
次のコードをneon_first_call.pyとして保存します。
import json
import os
from pathlib import Path
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
interaction = client.interactions.create(
model="gemini-4-neon",
input="List exactly three checks for confirming a new API integration works.",
store=False,
generation_config={
"thinking_level": "low",
"max_output_tokens": 65536,
},
)
Path("neon-response.json").write_text(
json.dumps(interaction.model_dump(mode="json"), indent=2), encoding="utf-8"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(interaction.output_text)
このリクエストには、意図して選んだ設定が3つあります。
thinking_level: "low":アクセス確認のコストを抑えます。指定しなければNeonはhighで思考します。まずlowで経路を確認し、その後で実際のワークロードに必要なレベルを設定します(ステップ5)。max_output_tokens: 65536:Neonのドキュメント上のデフォルト値で、1ホップあたりの上限でもあります。これは思考と表示出力を合わせた上限であって、請求額の予測ではありません。Googleは、古いアプリの8,192のような低い上限を引き継がないよう勧めています。支出を減らしたいなら、思考レベルを下げてください。store=False:この1回限りの呼び出しを保存対象から外します。background=Trueやprevious_interaction_idを使う場合は保存を有効(デフォルト)のままにしてください。どちらも保存済みのinteractionが必要です。有料ティアでは、保存されたinteractionをGoogleが55日間保持します。
同じリクエストをRESTで書くと次のとおりです。実際に送信される内容を確認するのに便利です。
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-neon",
"input": "List exactly three checks for confirming a new API integration works.",
"store": false,
"generation_config": {
"thinking_level": "low",
"max_output_tokens": 65536
}
}' \
--output neon-response.json
Interactions APIでは、generation_config内のフィールド名はPython、JavaScript、RESTのいずれでもsnake_caseです。output_textはSDKの便利なプロパティです。生のRESTレスポンスでは、テキストはtypeがmodel_outputのsteps項目の中の、typeがtextのcontentエントリに入っています。
--max-timeを900秒にしているのは、難しいプロンプトには少なくとも15分を見込むようにというGoogleの移行ガイドに従ったものです。簡単なプロンプトをlowで送れば、ずっと早く返ってくるはずです。クライアントがタイムアウトしても、サーバー側ではリクエストが処理(および課金)されている可能性があります。確認する前に自動リトライをかけないでください。
ステップ3:クライアントがgenerateContentを使っているならそのままでも可
generateContentは引き続きNeonで使えます。アプリケーションがすでにcandidatesを解析しているなら、モデル名と思考設定を変えるだけで済む場合があります。表記の違いに注意してください。generateContentのRESTはcamelCaseです。
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-neon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "List exactly three checks for confirming a new API integration works."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingLevel": "low"},
"maxOutputTokens": 65536
}
}' \
--output neon-response.json
Python SDKでは次のように書きます。
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-neon",
contents="List exactly three checks for confirming a new API integration works.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low"),
max_output_tokens=65536,
),
)
print(response.text)
print("Thinking tokens:", response.usage_metadata.thoughts_token_count)
Googleの思考ガイド(英語)のとおり、レベルの値はどちらの形式でも小文字の文字列("low"、"xhigh")です。2つのAPIを混ぜないでください。generation_config.thinking_levelはInteractionsの本文に、generationConfig.thinkingConfig.thinkingLevelはgenerateContentの本文に入れるものです。2つのAPI間でコードをコピーした後に400が出たら、まずフィールドの構造を確認します。また、古いthinkingBudget(thinking_budget)は削除してください。Gemini 4では非推奨で、思考レベルと一緒に送ると400が返ります。
コードパスごとにどちらか一方のAPIを選んでください。Interactions APIでは、サーバー側の状態(previous_interaction_id)とバックグラウンド実行を使えます。generateContentでは履歴を自分で管理し、過去のモデルのターンを思考シグネチャも含めて変更せずに送り返す必要があります。
ステップ4:呼び出しを信頼する前にステータス、テキスト、使用量を確認する
HTTP 200だけでは不十分です。interactionがcompleted以外のステータスで返ることがあり、generateContentのcandidateが思考に予算を使い切ってMAX_TOKENSで終わることもあります。どちらの場合も、表示可能なテキストがまったくないことがあります。Googleの長文出力ガイド(英語)は、Interactionsの各ステータスへの対処を次のように示しています。
| ステータス | 意味 | 対処 |
|---|---|---|
queued、in_progress | 実行中(バックグラウンド呼び出し) | 同じidでinteractions.getをポーリングする |
completed | 完了 | model_outputのテキストを連結し、usageを読む |
requires_action | モデルがツール呼び出しを要求した | ツールを実行し、このidで結果を送る |
requires_continuation | フォアグラウンドのホップが65,536の上限に達したが、予算が残っている | SDKはデフォルトで自動的に継続する。RESTではprevious_interaction_idとcontinuation_tokenを付けて次のホップを送る |
incomplete | max_output_tokensをすべて使い切った。テキストが空のこともある | 再開するか、max_output_tokensを増やして送り直す |
failed | サーバーが処理を完了できなかった | 1回だけリトライする。再度失敗したらサポート用にidを控える |
cancelled | 自分でキャンセルした | usageで課金された分を確認する |
generateContentでは、これに相当するのがfinishReasonの値です。STOPは成功、MAX_TOKENSは上限に到達、CONTINUATIONは次のホップが必要なことを意味します(最新のSDKは自動で継続します)。
次のチェッカーは、どちらのAPIで保存したレスポンスも読み取れます。ネットワーク通信は行わず、リトライもしません。
import json
import sys
from pathlib import Path
PENDING = {"queued", "in_progress"}
def check_interaction(p):
status = p.get("status")
if status in PENDING:
raise ValueError(f"Still {status}: poll interactions.get with this id later")
if status != "completed":
raise ValueError(f"Interaction status is {status}, not completed (see the status table)")
text = "".join(
c.get("text", "")
for s in p.get("steps", [])
if s.get("type") == "model_output"
for c in s.get("content", [])
if c.get("type") == "text"
)
u = p.get("usage") or {}
usage = {
"input": u.get("total_input_tokens"),
"cached_input": u.get("total_cached_tokens"),
"output": u.get("total_output_tokens"),
"thinking": u.get("total_thought_tokens"),
"tool_use": u.get("total_tool_use_tokens"),
"total": u.get("total_tokens"),
}
return text, usage
def check_generate_content(p):
cands = p.get("candidates") or []
if not cands:
reason = (p.get("promptFeedback") or {}).get("blockReason")
raise ValueError(f"No candidates (prompt block reason: {reason})")
c = cands[0]
reason = c.get("finishReason")
if reason != "STOP":
raise ValueError(f"finishReason is {reason}, not STOP")
text = "".join(
part.get("text", "")
for part in (c.get("content") or {}).get("parts", [])
if not part.get("thought")
)
u = p.get("usageMetadata") or {}
usage = {
"input": u.get("promptTokenCount"),
"cached_input": u.get("cachedContentTokenCount", 0),
"output": u.get("candidatesTokenCount"),
"thinking": u.get("thoughtsTokenCount"),
"tool_use": u.get("toolUsePromptTokenCount", 0),
"total": u.get("totalTokenCount"),
}
return text, usage
def check(payload):
if "error" in payload:
raise ValueError("API error: " + json.dumps(payload["error"]))
if "candidates" in payload or "promptFeedback" in payload:
text, usage = check_generate_content(payload)
elif "status" in payload or "steps" in payload:
text, usage = check_interaction(payload)
else:
raise ValueError("Unrecognised response shape")
if not text.strip():
raise ValueError("Completed, but no visible text")
return text, usage
if __name__ == "__main__":
path = sys.argv[1] if len(sys.argv) > 1 else "neon-response.json"
payload = json.loads(Path(path).read_text(encoding="utf-8"))
try:
text, usage = check(payload)
except ValueError as exc:
raise SystemExit(str(exc))
print("Usage:", json.dumps(usage))
print(text)
python3 check_neon.py neon-response.jsonを実行します。合格すると、正規化された使用量の行と表示可能な回答が出力されます。そのうえで回答そのものも読んでください。関連する3つのチェック項目が並んでいるべきで、拒否や途中で切れた文であってはいけません。
テストした内容。 上のチェッカーをそのままの形で、手書きの15件のフィクスチャに対して実行しました。内訳は次のとおりです。テキストが2つのmodel_outputステップに分かれ、思考ステップを1つ含む完了済みのinteraction。同じinteractionをgoogle-genai SDKのInteractionモデルとmodel_dump(mode="json")に通した版(ステップ2での保存形式)。in_progress、incomplete、requires_action、requires_continuation、failed、および完了したがテキストが空のinteraction。APIのエラー本文。generateContentのレスポンスとして、STOPで終わるもの(除外すべき思考パートを含む)、MAX_TOKENS、CONTINUATION、MALFORMED_FUNCTION_CALLで終わるもの、ブロックされたプロンプト、思考だけの回答。正しい形式の成功例3件は合格し、残りの12件は想定どおりのメッセージで終了しました。フィクスチャはドキュメント上のフィールド名に沿って作成したもので、実際に取得したNeonの出力ではありません。
Neonで注目すべき使用量フィールド
Neonのコストを左右する2つの要素、つまり思考とキャッシュヒットは、使用量の記録に表れます。
| 意味 | Interactions usage | generateContent usageMetadata |
|---|---|---|
| 入力トークン | total_input_tokens | promptTokenCount |
| キャッシュヒットした入力 | total_cached_tokens | cachedContentTokenCount |
| 表示出力 | total_output_tokens | candidatesTokenCount |
| 思考 | total_thought_tokens | thoughtsTokenCount |
| ツール使用のプロンプトトークン | total_tool_use_tokens | toolUsePromptTokenCount |
| 合計 | total_tokens | totalTokenCount |
フィールド名はGoogleのInteractionsとgenerateContentのAPIリファレンス(いずれも英語)によるものです。Googleのリファレンスの例(Neonではなく以前のモデル)では、思考が表示出力とは別に報告されています。1文の返答で、出力23トークンに対して思考が49トークンでした。Neonでは、思考は出力と同じ$15.00の単価で課金されます。Googleは、思考を含め、モデルが処理したすべてのトークンを数えます。グラウンディングを使う場合は、内部のシステム指示や関数宣言も含まれます。そのためhighやxhighでは、表示される回答が短くても出力料金が大きくなることがあります。毎回の呼び出しでthinkingとoutputを並べて記録してください。請求額がおかしいと感じたとき、最初に見るべきなのはこの2つの値です。
ステップ5:タスクごとに思考レベルを選ぶ
Googleのガイドは、4つのレベルを概ね次のように説明しています(要約)。
| レベル | Googleの説明 | 主な用途 |
|---|---|---|
low | トークンが最も少なく、レイテンシが最も低い | 高速なチャット、高スループット処理、低コストのアクセス確認 |
medium | トークン使用量が少なめで、応答が速い | 対話的なコーディング、UIのプロトタイピング、レイテンシに敏感なツール呼び出し |
high(デフォルト) | 知性と速度のバランス | 複雑なコーディングの大半、エージェントの実行、マルチモーダルな知識作業 |
xhigh | トークンが最も多く、推論が最も深い | 難しい多段階のエンジニアリング、highでは足りない分析・科学的な問題 |
Googleが推奨する方法は、上限で回答が切れないようmax_output_tokensを高めに設定して4つのレベルすべてでタスクを評価し、品質基準を満たす最も低いレベルを使うことです。xhighを指定するには次のようにします。
interaction = client.interactions.create(
model="gemini-4-neon",
input="Audit this retry queue for race conditions and rewrite the lock logic.",
generation_config={"thinking_level": "xhigh"},
)
Neon固有の注意点が2つあります。
xhighと65,536の上限は互いに影響します。 この上限は思考と出力の合計にかかります。Googleの思考ガイドは、テキストやJSONの抽出のような単純なプロンプトでは、xhighが考えすぎてmax_output_tokensを使い切ることがあると注意しています。MAX_TOKENSや、表示テキストがほとんどないincompleteのinteractionが出たら、まずタスクを見直してください。単純なタスクならレベルを下げます。本当に難しいタスクなら、レベルはそのままにして、バックグラウンド実行と大きめのmax_output_tokensで余裕を持たせます(後述のバックグラウンド実行のセクションを参照)。費用を抑えるためにmax_output_tokensを小さくするのはやめてください。Googleによれば、それでは回答が途中で切れるうえ、すでに行われた思考の分は課金されます。- Googleのコストに関する主張は、特定のレベルで測定されたものです。 GoogleのNeon発表によると、デフォルトの
highでNeonはArtificial Analysis Intelligence Indexで高いスコアを示しつつ、タスクあたりのコストがCarbonより32%低く、Neonの最高の知性スコアはxhighで得られています。Googleはこの32%をAA Intelligence Indexと結び付けていますが、Carbonのどの思考レベル、どの料金期間、どのAAデータのスナップショットと比較したかは示していません。2026年11月19日に確認したAAの数値では32%を再現できませんでした。比較の詳細はNeonの料金解説をご覧ください。これらはGoogleが報告したベンチマーク結果であり、読者のワークロードでの結果を予測するものではありません。上記の使用量フィールドで、自分のタスクを測定してください。
previous_interaction_idが引き継ぐのは会話履歴だけです。generation_config、tools、system_instructionは引き継がれないため、thinking_levelを付けずに送った後続ターンはNeonのデフォルトのhighに戻ります。ターンごとにレベルを送り直してください。
cachedContentsではなく暗黙的キャッシュを使う
Neonは暗黙的キャッシュのみに対応しています。caches.createでキャッシュを作成したりcached_contentを送ったりするコードを移行する場合は、それらのフィールドを削除してください。Googleのキャッシュガイドには、明示的キャッシュはInteractions APIでもGemini 4モデルでもサポートされていないと書かれています。
暗黙的キャッシュは、4,096トークン以上のプロンプトで自動的に働きます。ヒットした分は100万入力トークンあたり$3.00ではなく$0.15で課金され、95%の割引になります。ヒットを強制することはできませんが、Googleのキャッシュガイド(英語)は、確率を上げる方法を2つ挙げています。
- 大きく共通の内容(システム指示、リポジトリの構成図、参照ドキュメント)をプロンプトの先頭に置き、リクエストごとの質問を末尾に置く。
- 同じプレフィックスを持つリクエストを、時間的に近いタイミングで送る。
マルチターンのチャットやエージェントのループについて、GoogleはGemini 4向けのルールを追加しています。新しいリクエストが2,050トークン以上を追加した場合(モデルの出力、思考、関数の結果を含む)にのみ、前のリクエスト全体がキャッシュされます。追加が少ない場合は、前のリクエストの最後の2,050トークンが標準の入力料金で再処理されます。Googleによると、エージェントのターンの多くはこのしきい値を超えます。
最後に、思い込みではなくデータで確認してください。長いプレフィックスを共有する2回目以降のリクエストでは、total_cached_tokens(Interactions)またはcachedContentTokenCount(generateContent)が0以外になるはずです。0のままなら、先頭に挿入しているタイムスタンプやリクエストIDも含めて、プレフィックスがバイト単位で同一か確認してください。
64Kを超える出力:バックグラウンド実行
Neonの同期レスポンス1回は、思考と出力の合計65,536トークンで止まります。長い仕様書、大規模なリファクタリング計画、完全なテストスイートなどには、Googleはバックグラウンド実行を勧めています。
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-neon",
input="Write a complete migration specification and test plan for this service.",
background=True,
generation_config={"max_output_tokens": 262144, "thinking_level": "high"},
)
while interaction.status in ("queued", "in_progress"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
# 64Kごとの継続ホップすべてのテキストを連結する。
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(text)
サーバーは64Kずつのホップで継続するため、テキストは複数のmodel_outputステップに分かれて届きます。すべて連結してください(上のチェッカーも同じ処理をしています)。バックグラウンドのinteractionは最長24時間実行でき、failedで終わった場合はステータス表のとおり1回リトライします。見落としやすい点がさらに2つあります。max_output_tokensを指定せずにbackgroundを設定すると、サーバーはやはり65,536トークンで停止します。また、バックグラウンド実行には保存が必要なので、store=Falseと組み合わせないでください。上限は1,048,576から入力トークン数を引いた値です。interactionを保存できない場合のクライアント側の継続については、Googleの長文出力ガイド(英語)を参照してください。
Gemini 4 Neon APIのよくあるエラーと対処法
何かを変更する前に、エンドポイント、正確なモデルID、プロジェクト、SDKのバージョン、エラー本文の全体(キーは除く)を記録してください。最初に失敗した層から直します。
| 症状 | Neonで考えられる原因 | 対処 |
|---|---|---|
| Hydrogenでは使えるキーでアクセスエラーやクォータエラーが出る | キーが無料ティアのプロジェクトに属している。Neonは有料ティア専用 | 有料の課金が有効なプロジェクトのキーを使う(ステップ1) |
| モデルが見つからない | タイプミス、-previewのような存在しないサフィックス、またはNeonをルーティングしないゲートウェイ | generativelanguage.googleapis.comに対してgemini-4-neonを使う |
thinking_levelで400 | minimalを送った(Gemini 4では拒否される)、InteractionsとgenerateContentのフィールド構造が混在している、または古いthinkingBudgetをレベルと一緒に送った | low/medium/high/xhighを使う。フィールド名をエンドポイントに合わせる。thinkingBudgetを削除する |
| サンプリングパラメータで400の検証エラー | temperature、top_p、top_kが範囲外 | サンプリングパラメータを削除する。範囲内の値もどのみち無視される |
| キャッシュのコードを移行した後にリクエストが失敗する | 古いcached_content/cachedContentsの参照が残っている(明示的キャッシュは非対応) | 削除し、暗黙的キャッシュに任せる |
MAX_TOKENS、incomplete、またはテキストが空 | 低いmax_output_tokensが思考で使い切られた | 65,536に戻す、長い作業にはバックグラウンド実行を使う、または意図的に思考レベルを下げる |
MALFORMED_FUNCTION_CALL | ツールを宣言せずに、生テキストのJSONでツール呼び出しを出すようモデルに指示した | Function callingでツールを宣言するか、構造化出力を使う |
| マルチターンのツール使用でシグネチャエラー | 思考シグネチャが落ちている、または並列呼び出し間でコピーされている | previous_interaction_idを使うか、過去のターンを変更せずに返す。思考シグネチャ欠落の対処法を参照 |
| 難しいプロンプトでクライアントがタイムアウトする | high/xhighの推論には数分かかる | HTTPタイムアウトを15分以上にするか、バックグラウンド実行を使う |
| 429 | 有料ティアでもレート制限は適用される | 並列数を減らしてバックオフする。429リトライガイドを参照 |
表の大部分は、GoogleのNeon移行チェックリストをそのまま反映したものです。同系統のモデルでルーティング、クォータ、レスポンスを診断する具体例は、Gemini 4 Argon APIエラーの解説を参照してください。ただし、そこにあるArgon固有の値(デフォルトの思考レベル、選べるレベル)はNeonには当てはまりません。Carbon・Neon・Hydrogenのエラー(回答が空になる、途中で切れるケースを含む)は、Gemini 4 Carbon・Neon・Hydrogenのエラー対処ガイドにまとめています。
Gemini 4 NeonはOfox経由で使えますか?
2026年11月19日時点では使えません。Ofoxのモデル一覧はGemini 4 HydrogenとArgonを返し、Neonは含まれていませんでした。Neonのモデルページのパスも404でした。上のコードをOfoxのBase URLに向けないでください。InteractionsのエンドポイントとOfoxのキーは別のシステムで、そもそもNeonへのルートがありません。
後で改めて確認するには、Ofoxのモデル一覧(OfoxのキーでGET https://api.ofox.io/v1/models)かofox.ai/modelsでgoogle/gemini-4-neonを探してください。掲載されていれば、そのモデルページに対応プロトコルと現在の料金が表示されます。OfoxでのGeminiモデルのリクエスト形式はOfox Gemini APIドキュメントにあります。エンドポイントと認証はそのドキュメントに従い、本記事のGoogleネイティブのコードがそのまま使えるとは考えないでください。
今すぐOfox経由でGemini 4モデルを使いたい場合は、Gemini 4 Hydrogenが掲載されており、そのセットアップガイドでOfoxの経路も説明しています。Googleが比較対象としたライバルのフラッグシップとNeonの比較は、Gemini 4 Neon、Claude Opus 5.5、GPT-6.2 Solの比較を参照してください。
初回呼び出しの受け入れチェックリスト
Neonとの連携を完了とする前に、秘密情報を含まない次の記録を残してください。
- モデルID
gemini-4-neon、エンドポイント、SDKのバージョン、プロジェクトの識別子。 - チェッカーに合格した保存済みレスポンス1件(
completedまたはSTOPで、テキストが空でないもの)。 - 使用量の行。思考トークンとキャッシュ入力トークンは分けて記録する。
- 送信した
thinking_levelとmax_output_tokens。デフォルトに任せず、コード内に明示的に書いたもの。 - 遭遇したエラーと、それを直した変更。
このベースラインができたら、ツール、長いドキュメント、バックグラウンドジョブを1つずつ追加してください。何かが失敗したとき、原因が新しく加えた部分だと分かります。
関連ドキュメント
- Ofox Gemini APIドキュメント:Ofoxで利用できるGeminiモデルのリクエスト形式
- Ofoxエラーハンドリングガイド:Ofoxの経路でのエラーの読み方とリトライ
- Ofoxのレート制限:現在のデフォルトの制限と引き上げの申請方法
- Google: What’s new in Gemini 4 Neon(英語):公式のモデルガイドと移行チェックリスト


