Gemini 4 Argon API：Pythonでネイティブのストリーミング会話を作る
PythonでGemini 4 Argon APIの会話を実装。ネイティブSSEの読み取り、署名付きコンテンツの保持、空の回答への対処、トークン使用量の確認を解説します。
Markdown で読むGemini 4 Argon APIの会話では、contents、ロール、partsというGeminiネイティブのコンテンツを使います。最初のリクエストは小さなものです。難しいのは、追加の質問を送る前に応答を正しく保存することです。表示されたテキストだけでモデルのターンを組み立て直すと、署名付きコンテンツが失われる場合があります。空の読み込み中メッセージを履歴に入れると、次のリクエストが無効になることもあります。
このチュートリアルではPythonの標準ライブラリとSeedRouterのネイティブエンドポイントを使い、テキストチャットとストリーミングを扱います。全パラメータの仕様はAPIリファレンスにまとめています。この記事では、1つのリクエストから実用的な会話へ進む流れを説明します。
最初のリクエストを送る前に
Python 3、SeedRouterのAPIキー、十分なアカウント残高が必要です。キーはSEEDROUTER_API_KEYという環境変数に保存し、ソースコードやブラウザに配信するバンドルには含めないでください。送信する各メッセージには料金が発生する場合があります。この例では、リクエストの自動再試行や継続リクエストの呼び出しを行いません。
モデルIDはgemini-4-argonで、エンドポイントのパスに指定します。Googleのネイティブ生成ガイドにこの形式の説明があります。SeedRouterは、以下に示すBearer認証を使います。
Gemini 4 Argon APIに1件のリクエストを送る
curl --no-buffer --fail-with-body \
'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'応答は単一のJSON文書ではなく、サーバー送信イベントの連続です。各data:イベントにはGeminiネイティブのJSONが含まれます。表示用のテキストはcandidates[].content.parts[].textに入りますが、思考や署名が入るパートもあります。usageMetadataはテキストとは別に届く場合があるため、回答が完了したと判断する前に最後のイベントまで読み取ってください。
ここでは簡単な動作確認のため、出力予算を意図的に小さくしています。思考も同じ予算を消費するので、応答が未完了になる可能性があります。難しい作業では必要に応じて予算を増やしてください。未完了の回答を、利用者に見えない再試行ループにつなげないでください。
Pythonで2ターンの会話を実行する
Pythonの完全なサンプルをダウンロードしてローカルに保存し、実行します。
python3 gemini-4-argon-chat.py最初に「Explain a mutex in one sentence」、次に「Give a Python example of that idea」と質問します。スクリプトは各リクエストの前に入力を待ちます。空行を入力すると終了します。履歴を扱う基本ルールは次のとおりです。
user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]ダウンロードできるスクリプトには生成設定も含まれています。SSEフレームを解析して思考以外のテキストだけを表示し、終了理由がSTOPでpartsが空ではない場合に限って履歴を確定します。APIエラー、ストリームの中断、空の回答が発生しても、それまでの履歴は変わりません。メッセージを無断で再送することもありません。
上の短いコードはデータ構造を示すためのものです。リクエスト処理全体を動かすには、完全なファイルを実行してください。非ストリーミング応答に対応する操作はgenerateContentです。リファレンスの例ではcURL、Python、Node.js、Goを紹介しています。
読み込み表示ではなくネイティブのpartsを保存する
2件目のリクエストには、最初のユーザーメッセージ、完了したモデル応答、2件目のユーザーメッセージという3つの実際のターンが必要です。UIに表示する「思考中…」は、別のモデルターンではありません。
たとえばcontents.3.parts: Too small: expected array to have >=1 itemsというエラーは、4番目のコンテンツ要素のparts配列が空であることを示します。インデックスは0から始まります。プロンプトやモデルを変更する前に、履歴の組み立て方を調べてください。読み込み表示は画面の状態として管理し、リクエスト内の{ "role": "model", "parts": [] }にしてはいけません。
返されたパートは、thoughtSignatureや思考とマークされたパートも含めて、すべて順番どおりに保持してください。画面に表示しない場合も同じです。Googleの思考署名ガイドでは、これらの不透明なフィールドを後続ターンにも引き継ぐ必要がある理由を説明しています。署名を編集、捏造、再構成しないでください。ネイティブの履歴は、画面に表示するテキストとは分けて保存します。
ツールを使う会話でも、同じ保持原則が適用されます。ただし、ツールを実行して結果を返すには、より大きなアプリケーションの処理ループが必要です。このテキスト用サンプルはそのループを実装しておらず、完全なコーディングエージェントとして紹介すべきものではありません。
使用量の読み取りと停止時の処理
生のリクエストでは、ストリームで最後に報告された使用量を保持します。同じリクエスト内で繰り返し届く累積スナップショットを合計しないでください。通常の入力はpromptTokenCountからcachedContentTokenCountを引いた量です。課金対象の出力には、candidatesTokenCountとthoughtsTokenCountの両方が含まれます。料金ガイドでは、この数値を予算に換算する方法を説明しています。
Ctrl+Cでサンプルを停止すると、それ以上のリクエストは送られません。ただし、ローカルで読み取りを止めても、リモートの生成でトークンが使われなかったことにはなりません。使用量が届く前にストリームが終了した場合は、アカウントの使用履歴を確認してください。この例は安全側の処理として、未完了のターンを後続の履歴に含めません。部分的な回答を保存するかどうかは、別途決めるアプリケーション設計上の判断です。
長い出力の継続生成は、これとも異なる処理です。終了理由CONTINUATIONでは、継続トークンで元の生成を再開します。新しいユーザーメッセージではありません。Googleは元のリクエストと最新のトークンを使い、部分的な出力をcontentsに追加しないよう求めています。長い出力の継続生成ガイドをご覧ください。この入門スクリプトは自動継続を実装せず、その時点で停止します。
検証済みなのはどこまでですか？
基本的なテキストのストリーミングは、SeedRouter Playgroundを通じたローカル環境でのエンドツーエンド確認に合格しています。サンプルの解析と履歴処理は、署名付きパート、空の応答、中断を含む合成ストリームで確認しています。これらのテストデータはソフトウェアの検査であり、モデルを追加で実行した結果ではありません。ツール、メディア、継続生成を検証済みの連携と呼ぶには、それぞれの機能確認が必要です。
APIについての質問
OpenAIのモデル名をgemini-4-argonに置き換えるだけで使えますか？
名前を替えるだけではメッセージ形式は変換されません。このガイドではGeminiネイティブのcontentsとpartsを使っています。クライアントがそのプロトコルと、設定した認証方式およびエンドポイントに対応しているか確認してください。
トークンを使ったのに回答が空なのはなぜですか？
思考が出力予算を使い切る場合があります。安全性の制約や生成の未完了によって、表示できるテキストが返らないこともあります。終了理由と使用量を確認してください。空のモデルターンを追加したり、有料リクエストを自動で繰り返したりしないでください。
100万トークンのコンテキストなら100万トークン出力できますか？
いいえ。入力、思考、出力でコンテキストを共有します。長い生成にはリクエストごとの上限もあり、継続が必要な場合があります。入力と出力の枠を別々に考えるのではなく、共有する合計量に対して予算を立ててください。
会話が動いてから機能を追加する
まず1つの完全な回答を受け取り、2ターン目に元のネイティブコンテンツが引き継がれることを確認します。添付ファイル、ツール、永続化を加える際も、Gemini 4 Argon APIの履歴と表示状態を分けて管理してください。対話的な利用やアカウント要件については、モデルのPlaygroundとアクセスガイドをご覧ください。
