Gemini チャット

2 つの Gemini プランでは対応パラメータが異なります。接続前に下記の「プランごとの機能差分」を確認してください。

最初のリクエスト

Gemini のチャットモデルは OpenAI Chat Completions、OpenAI Responses、Anthropic Messages の 3 つのプロトコルで呼び出せます。以下は Chat Completions の例です。認証は Authorization: Bearer sk-your-key で、x-api-key も受け付けます。

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

利用できる Gemini モデルはプランによって異なります。まず現在のキーで GET /v1/models を呼び出し、レスポンスに含まれる完全な ID のみを使用してください。

x-goog-api-key と /v1beta/models/{model}:generateContent には対応していません。2 つの Gemini プランはどちらも /v1/chat/completions、/v1/responses、/v1/messages に対応し、「Gemini 公式ダイレクト」ではさらに /v1/messages/count_tokens(ローカル推定、課金なし)を利用できます。プロトコルごとの細かな違いは下の「プランごとの機能差分」を参照してください。

利用可能なモデル

既定では gemini-3.8-flash を使用してください。ID に preview を含むモデルはすべてプレビュー版として扱い、安定性は保証されません。

料金はプランによって異なります。現在のキーのプランと、ログイン後のモデルカタログが正となります。

プランごとの機能差分

「Gemini 全モデル（画像生成含む）」の構造化出力は、response_format の json_object と json_schema に対応しています。

「Gemini 公式ダイレクト」:Chat Completions のパラメータ

• messages:対応するコンテンツパートは text、image_url、input_audio、file、refusal で、それ以外のタイプは 400 になります。image_url は base64 の data URL のみ受け付けます。file の file_data は data URL である必要があり、file_id には対応していません。role: "tool" の結果は関数の結果としてモデルに渡されます。
• tools / tool_choice:tool_choice は auto、none、required、関数指定、allowed_tools に対応し、並列ツール呼び出しとマルチターンにも対応します。parallel_tool_calls: false の場合は最初の呼び出しのみ残ります。旧形式の functions / function_call も使えます。ツールのパラメータ schema は完全な JSON Schema として受け付けるため、$ref、$defs、anyOf、additionalProperties などを書き換える必要はありません。
• response_format:json_object と json_schema に対応します。
• stop:文字列または配列。n:1〜8 で、その数の choices を返します。
• max_tokens / max_completion_tokens:両方送ると max_tokens が優先され、思考トークンもこの上限に含まれるため 4096 以上を推奨します。
• temperature / top_p:モデルの公式範囲のまま転送されます。seed と top_k にも対応します。
• presence_penalty / frequency_penalty:0 の場合は無視されます。0 以外はそのまま送られ、現在の Gemini モデルでは 400 Penalty is not enabled for this model が返ります。
• reasoning_effort:思考予算に変換されます(下記「思考」を参照)。
• 400 を返すフィールド:logprobs、top_logprobs、logit_bias、modalities、audio、web_search_options(modalities は text 以外の値を含む場合のみ)。
• 無視され出力に影響しないフィールド:user、metadata、store、service_tier、safety_identifier、prompt_cache_key、stream_options、prediction、verbosity。

フィールドの一般的な説明は API リファレンス Chat Completions を参照してください。

「Gemini 公式ダイレクト」:Responses と Anthropic Messages

• ツール:function ツールと custom 自由テキストツール(Codex の apply_patch など)に対応します。組み込み / ホスト型ツール(web_search、file_search、code_interpreter、computer など)は 400 になります。tool_choice の値は Chat Completions と同じで、max_tool_calls は呼び出し数を切り詰めます。
• ステートレス:previous_response_id、conversation、background、prompt テンプレート、item_reference は 400 になります。毎回のリクエストで input に完全な履歴を含めてください(Codex は既定でそうしています)。
• 構造化出力は text.format を使います。
• 無視され出力に影響しないフィールド:store、include、user、metadata、safety_identifier、prompt_cache_key、service_tier、truncation、text.verbosity。

• Base URL は https://api.hop-base.com(/v1 なし)を指定します。Claude Code は CC Switch 経由で直接接続できます。モデル名には gemini-3.8-flash などの Gemini モデル ID を指定してください。claude-* の名前は自動では対応付けられません。
• tool_choice は auto、any、tool、none に対応します。disable_parallel_tool_use: true の場合は最初の呼び出しのみ残ります。
• image / document は base64 ソースのみ受け付け、url ソースは 400 になります。tool_result には画像を含められます。
• 構造化出力は output_format または output_config.format(json_schema)を使います。
• /v1/messages/count_tokens はローカル推定で、課金されません。
• 無視され出力に影響しないフィールド:metadata、service_tier、cache_control、context_management。

思考シグネチャ(マルチターンのツール呼び出し)

Gemini 3 以降のモデルのツール呼び出しには「思考シグネチャ」が付きます。各プロトコルでの位置:

次のターンではアシスタントのメッセージをそのまま送り返してください。クライアントがこれらのフィールドを落としてもエラーにはなりません。ゲートウェイができる限り復元し、復元できない場合は公式の方法で検証をスキップします。その場合、推論の一貫性がやや下がることがあります。

SSE ストリーミング("stream": true を追加)

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro-preview", "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]}'

「Gemini 公式ダイレクト」プランでは 3 つのプロトコルすべてが "stream": true に対応し、イベント形式はそれぞれ OpenAI Chat Completions、OpenAI Responses、Anthropic Messages の仕様に従います(ツール呼び出しの差分を含む)。ストリーミングは応答全体の生成完了後にまとめてチャンク送信される場合があり、最初のチャンクが届くまでの時間は完全な生成時間とほぼ同じになることがあります。これは 3 プロトコルとも同様です。Chat Completions の最後のチャンクには必ず usage が含まれます。

「Gemini 全モデル（画像生成含む）」プランはトークン単位でストリーミングします。usage が必要な場合は stream_options.include_usage を追加してください。

ストリーミングでないレスポンスは、usage に課金額を含みます。cost_usd は残高から実際に差し引かれた米ドル額、cost は同じ課金額の人民元額、currency は cost の通貨(常に CNY)で、レスポンスヘッダー X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency も同じ値です。ストリーミングのレスポンスはいずれも含まないため、課金額はコンソールの「使用記録」で確認してください。課金額を参照してください。

思考

Gemini モデルはデフォルトで思考を行い、完全にオフにすることはできません。思考トークンは出力上限に含まれます。max_tokens が小さすぎると、本文が数文字のまま finish_reason=length になることがあるため、4096 以上を推奨します。

OpenAI 形式では思考トークンはすでに completion_tokens に含まれ、さらに completion_tokens_details.reasoning_tokens に個別集計されます(「Gemini 公式ダイレクト」の Responses では output_tokens_details.reasoning_tokens)。ネイティブ形式では usageMetadata.thoughtsTokenCount に個別に報告されます。

「Gemini 公式ダイレクト」プランでは reasoning_effort が思考予算に変換されます:

gemini-4-argon は思考レベルのみ受け付け、上表の予算は使いません:none / minimal → low、medium → medium、high → high。low は指定なしと同じくモデルの既定レベルになります。思考を完全にオフにすることはできません。

Responses で reasoning.summary を有効にすると reasoning の要約が返ります。Anthropic Messages で thinking.type を enabled または adaptive にすると thinking ブロックが返り、budget_tokens は 24576 を超えると 24576 に切り詰められます。

「Gemini 公式ダイレクト」の課金:思考トークンは出力として、組み込みツールがモデルに返すトークン(toolUsePromptTokenCount)は入力として課金されます。usage は各プロトコルの標準形式で返り、Anthropic Messages の input_tokens にはキャッシュ読み取りが含まれず、キャッシュ読み取りは cache_read_input_tokens に入ります。

「Gemini 全モデル（画像生成含む）」プランでは none を渡すと思考量が明確に減ります。

Gemini ネイティブ形式のパススルー

Gemini SDK から移行する既存のリクエストボディはそのまま送信できます。「Gemini 公式ダイレクト」プランの同じエンドポイントは Gemini ネイティブの contents フィールドも受け付け、レスポンスもネイティブ形式で返されます。

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "contents": [{"role": "user", "parts": [{"text": "Hello"}]}]
  }'

ネイティブ形式で受け付けるのは公式のトップレベルフィールドのみです:

contents, systemInstruction, generationConfig, safetySettings, tools,
toolConfig, cachedContent, labels, serviceTier, model

store、max_tokens、messages などそれ以外のフィールドを含めると 400 Unknown name … が返ります。ネイティブ形式はストリーミングに対応していないため、"stream": true を送らないでください。

次のステップ

• Gemini の画像生成(Banana)は画像生成 APIを参照してください
• エラーが出たときはエラー早見表を参照してください