チュートリアル
HiAPI 上の Gemini-4 Argon と Carbon:curl、Python と実行可能なリクエスト
gemini-4-argon、gemini-4-carbon、gemini-4-carbon@vertex のどれを選ぶか判断する開発者向けの実践的統合ガイド
このページの内容
コードを書く前に Gemini-4 バリアントを選ぶ
Gemini-4 統合における最初の決定は curl か Python かではなく、どのモデル ID を送信するかです。HiAPI では、gemini-4-argon、gemini-4-carbon、gemini-4-carbon@vertex は 3 つの異なるルーティング可能なターゲットであり、model フィールドに渡す文字列によって、どのバックエンドがリクエストを処理するかが決まります。これを早めに決めておけば、そもそも動作しないリクエストボディをデバッグする手間を省けます。
実践における 3 つのターゲット
gemini-4-argon—— 独自のモデル ID を持つ独立した Gemini-4 バリアントです。エイリアスではなく、それ自体を 1 つのモデルとして扱ってください。その挙動、レイテンシ特性、出力特性は Carbon と異なる可能性があります。gemini-4-carbon—— HiAPI 標準ルーティングにおけるデフォルトの Carbon ターゲットです。gemini-4-carbon@vertex—— 同じ Carbon シリーズですが、Vertex を基盤とするルーティング経由で提供されます。@vertexサフィックスはモデル ID 自体の一部であり、別個のパラメータではありません。
選び方
ワークロードから出発してください。Gemini-4 を広く評価しているのであれば、gemini-4-argon と gemini-4-carbon の両方に対して同じプロンプトを実行し、確定する前に出力を比較してください。Vertex ルーティングが本当に必要な場合——たとえばチームがすでに運用している環境と一致するからという理由など——は、直接 gemini-4-carbon@vertex をターゲットにしてください。
実用的なポイント:これら 3 つはすべて同じリクエスト構造を使用します。バリアントの選択は 1 行を変えるだけなので、動作するリクエストを手にしてから最終決定を下すことができます。先にモデルカードを確認したい場合は、gemini-4-argon と gemini-4-carbon を参照してください。
このガイドの例では一貫して gemini-4-carbon を使用します。どのバリアントに従う場合でも、その ID を置き換えるだけで済みます。
認証情報とベース URL を準備する
リクエストボディが重要になる前に、まず 3 つのことを正しくしておく必要があります。ベース URL、API キー、そして認証ヘッダーの形式です。初回リクエストの失敗のほとんどはこの 3 つのいずれかに起因します。
必要なもの
- API キー。HiAPI アカウントのダッシュボードから取得します。秘密情報として扱い、ソースファイルに貼り付けるのではなく環境変数から読み込んでください。
- HiAPI ベース URL。 すべてのモデル呼び出しは同じホストに送信されます。モデルバリアントはパスではなく
modelフィールドで選択されます。 - すべてのリクエストに 2 つのヘッダーを付ける:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
環境を設定する
export HIAPI_API_KEY="your-key-here"
次に、コードを書く前にシェルがそれを認識しているか確認します:
echo "${HIAPI_API_KEY:0:4}..."
何も表示されない場合、キーが現在のシェルでエクスポートされておらず、すべてのリクエストが認証エラーで失敗します。クライアント側ではなく、ここで修正してください。
繰り返し使うリクエスト構造
以下のすべての例は、model 文字列と messages 配列を含む JSON リクエストボディを送信します。この構造は curl と Python の間でも、非ストリーミングとストリーミングの間でも、モデルバリアントの間でも変わりません。これを安定させておけば、リクエストボディをコピーするだけでコードを移植できます。
動作する curl リクエスト
以下は完全で、そのままコピー&ペーストできる非ストリーミング呼び出しです。他の何かを追加する前にまずこれを実行してください——ここでリクエストが通れば、キー、ベース URL、ヘッダーが正しいことが証明されます。
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."}
]
}'
各フィールドの役割
model—— バリアントセレクターです。これをgemini-4-argonやgemini-4-carbon@vertexに変更すれば、他の何も変えずに異なるターゲットにヒットします。messages—— 順序付きの配列です。ロールにはsystem、user、assistantがあります。システムメッセージを使う場合は先頭に置いてください。content—— メッセージテキストです。単純なテキストのターンでは通常の文字列です。
レスポンスボディを読む
レスポンスは、モデルの返答とトークン使用量などのメタデータを含む JSON オブジェクトです。これは非ストリーミングなので、ボディ全体が一度に届き、curl は出力後に終了します。メッセージ返答を含むパース可能な JSON オブジェクトが得られれば、リクエストは通っています——以降のすべてはこのベースラインの上に築かれます。
簡単な健全性チェック:出力を JSON フォーマッター(| jq .)に通せば、1 行の長いテキストではなく、レスポンス構造が読みやすく整います。
同じリクエストを Python で送る
Python 版はリクエストボディを完全に同一に保ちます——変わるのは転送方法だけです。requests を使います:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
これが curl 呼び出しと完全に対応する理由
payload が前節の JSON リクエストボディとバイト単位で同一であることに注目してください。json= 引数がそれをシリアライズし、Content-Type を自動で設定します。ヘッダーディクショナリが認証を提供します。モデル、メッセージ、ロールのいずれも変わっていません。
維持する価値のある 2 つの習慣
- タイムアウトを設定する。 タイムアウトがないと、接続が停滞したときにプロセスが無限にハングします。非ストリーミング呼び出しでは
timeout=60が妥当な出発点です。 - レスポンスボディを読む前に
raise_for_status()を呼ぶ。 失敗したリクエストは補完結果ではなく構造化されたエラーオブジェクトを返すため、4xx でjson()をチェックすると誤解を招きます。まず例外を発生させ、それからレスポンステキストをログに記録してください。
リクエストボディを関数または小さな設定オブジェクトにまとめておけば、ストリーミングやツール呼び出しの節でそれをコピーするのではなく拡張できます。
呼び出しにストリーミングを追加する
まず非ストリーミングリクエストを通してください。それからストリーミングを有効にします——失敗モードが異なるため、2 つの変更を同時に重ねるとエラーの切り分けが難しくなります。
ストリーミングを有効にする
既存のリクエストボディにフィールドを 1 つ追加します:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "List three uses for a message queue."}
]
}
プロトコルの変更はこれだけです。サーバーは 1 つの JSON ドキュメントではなく、一連のイベントを返すようになります。
ストリームを正しく消費する
重要なルール:ストリーミングレスポンスに対して .json() を呼ばないでください。 レスポンスボディが単一の JSON オブジェクトではないため、パースエラーになります。requests を使う場合は、行ごとに反復して各チャンクを個別にパースします:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "List three uses for a message queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
注意すべきこと
requestsにstream=Trueを渡す。 そうしないとクライアントがレスポンスボディ全体をバッファリングし、その後でようやく 1 行が表示されるため、本来の目的が果たせません。- 空行と JSON でないキープアライブメッセージをスキップする。 上記の
try/exceptは意図的なものです——ストリームにはチャンクとしてパースできない行が含まれる場合があります。 - チャンクをまたいでテキストを蓄積する。 各チャンクは完全な返答ではなく断片を運びます。テキストの差分が届いたら順に追加してください。
ストリーミングが動作したら、非ストリーミングのテストでは stream を false に戻し、ツール呼び出しを読みやすく保ってください。Carbon ターゲットの概要については、gemini-4-carbon モデルページ が良い参照点です。
リクエストボディにツール呼び出しを追加する
ツール呼び出しは 2 か所でリクエストを変えます。ツールを宣言すること、そしてテキストではなくツール呼び出しリクエストを含む可能性のあるレスポンスターンを処理することです。この機能は非ストリーミングのテキスト呼び出しが通ってから追加してください。
ツールを宣言する
model と messages の隣に tools 配列を追加します。各ツールには名前、説明、そしてその引数の JSON Schema があります。説明は重要です——モデルがそのツールを呼ぶべきかどうかを判断する根拠になるからです。
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
}
ツール呼び出しループ
ツールを使うリクエストは単発の呼び出しではなく会話です:
- 送信する:ユーザーメッセージとツール宣言。
- 確認する:アシスタントターン。ツール呼び出し引数が含まれていれば、モデルは何かを実行してほしいと考えています。
- 実行する:ローカル関数——HiAPI はあなたのコードを実行しません。
- 追加する:2 つのメッセージ。アシスタントのツール呼び出しターンと、一致する呼び出し ID に関連付けられた関数結果を持つ
toolロールメッセージです。 - 再送信する:完全なメッセージ履歴。モデルは今度は最終回答を生成します。
ツール特有の失敗ポイント
- Schema の不一致。
parametersschema がフィールドを必須としているのに結果で省略された場合、以降のターンが拒否されることがあります。schema は正確に保ってください。 - 履歴の破棄。 再送信のたびに、元のユーザーメッセージとツール呼び出しターンを含める必要があります——ツール結果だけではいけません。
- ストリーミングとツールの併用。 ツール呼び出し引数は複数のストリームチャンクに分割されて届く場合があります。フローを学ぶ間は
stream: falseでツールを実行し、各ターンが読みやすいオブジェクトとして届くようにしてください。
クライアントを書き直さずにモデルとプロバイダーを切り替える
モデルバリアントはリクエストボディ内の文字列にすぎないため、ターゲットの切り替えはリファクタリングではなく設定変更です。クライアントはモデル ID を変数——環境変数、設定ファイル、CLI フラグ——から読み取るように設計し、複数箇所にハードコードしないでください。
切り替えそのもの
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
コード内では、リクエストボディでその変数を参照します:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
@vertex サフィックスはモデル文字列と一緒に渡されます。別フィールドに分割したり削除したりしないでください——それはルーティング可能な ID の一部であり、削除すると黙って非 Vertex ターゲットにルーティングされます。
切り替え後に再テストすべきこと
- プレーンテキストのターン —— ID が認識され、認証が引き続き有効であることを確認します。
- 最も長い実際のプロンプト —— バリアントによって長い入力や構造化入力の扱いが異なる場合があります。切り詰めとフォーマットを検証してください。
- ストリーミング —— チャンクのタイミングや境界がターゲットによって異なる可能性があるため、ストリーミングパスを再実行します。
- ツール呼び出し —— 完全なツール呼び出しループを再検証します。引数のフォーマットはバリアントの違いが最も露呈しやすい箇所です。
現在設定されている HIAPI_MODEL に対してこれら 4 つのチェックを実行する小さなスモークテストスクリプトを保持してください。そうすればプロバイダーの切り替えは、デバッグセッションではなく設定変更と 1 つのコマンドになります。
よくあるリクエスト失敗のトラブルシューティング
統合の失敗はほぼすべて少数のカテゴリに分類できます。症状を照合し、修正を適用し、他の何かを変える前に非ストリーミングのベースラインを再実行してください。
認証とルーティング
- 401 または 403。 キーが欠落、期限切れ、またはプレフィックスが正しくありません。ヘッダーが正確に
Authorization: Bearer <key>であり、間にスペースが 1 つだけであることを確認し、その変数がコードを実行しているシェルまたはプロセスで実際にエクスポートされていることを確認してください。最初の数文字を出力して確認します。 - エンドポイントが 404 を返す。 ベース URL が間違っているか、パスセグメントが重複しています。モデルは URL ではなくリクエストボディに入ります。
- モデルが見つからない。 モデル ID に誤字があります。
gemini-4-argon、gemini-4-carbon、gemini-4-carbon@vertexを 1 文字ずつ照合してください——@vertexサフィックスは最も見落とされやすい箇所です。
リクエストボディの問題
- schema メッセージを伴う 400。 通常は
messagesの形式エラーです:roleの欠落、contentが文字列であるべきなのにそうでない、または配列が空。このガイドの最小の 2 行のリクエストボディから始め、フィールドを 1 つずつ追加してください。 - ツール追加後の 400。
parametersschema が無効な JSON Schema であるか、ツール結果ターンがアシスタントメッセージ内の呼び出し ID と一致していません。レスポンスボディ全体をログに記録してください——エラーテキストが問題のフィールドを指し示します。
ストリーミングの失敗
- レスポンスでの JSON パースエラー。 ストリームに対して
.json()を呼んでいます。代わりに行ごとに反復して各チャンクをパースし、空行と[DONE]マーカーをスキップしてください。 - レスポンスが一度に届く。 クライアント呼び出しで
stream=Trueを設定し忘れており、requestsがレスポンスボディ全体をバッファリングしています。 - 出力が切り詰められる。 ループが早期に中断しています——多くの場合、空行やキープアライブメッセージで止まっています。明示的なストリーム終了マーカーでのみ停止してください。
デバッグの規律
構築したときと同じ順序で二分探索してください:認証とヘッダー、次に非ストリーミングテキスト、次にストリーミング、次にツール。各層は異なる失敗特性を持つため、最後に変更したものがほぼ常に原因です。失敗のたびに HTTP ステータスとレスポンスボディ全体をログに記録してください——メッセージが通常、具体的なフィールドを指し示します。
まず gemini-4-argon または gemini-4-carbon でベースラインを通し、そこからリクエストボディを拡張してください。どのバリアントが自分のワークロードに適しているかまだ決めかねている場合は、gemini-4-argon モデルページ が出発点になります。