Interactions API

Interactions API は、Gemini のモデルとエージェントを構築する最も簡単で最適な方法です。2026 年 6 月より一般提供が開始され、すべての新しいプロジェクトにおすすめします。現在はレガシーと見なされていますが、元の generateContent API は引き続き完全にサポートされています。

Interactions API を使用する理由

  • すべてのアプリケーションに対応するユニバーサル インターフェース: 単一ターンのテキスト生成、マルチモーダル理解、構造化出力、ツール オーケストレーション、エージェント ワークフローなど、あらゆるユースケースに対応する標準インターフェースとして設計されています。
  • モデルとエージェントに対応する単一の API: 標準の Gemini モデルと、専門のエージェント（Deep Research やカスタム マネージド エージェントなど）を直接呼び出すための、統合されたエンドポイントとパターンです。
  • すぐに使える新機能: previous_interaction_id を使用したサーバーサイドの会話状態（オプション）、デバッグと UI レンダリングのための実行ステップのモニタリング、バックグラウンド実行 を使用した長時間実行タスクのバックグラウンド実行などの機能があります。background=true
  • キャッシュ ヒット率の向上とコスト削減: マルチターンの会話を使用する場合、サーバーサイドの状態管理（オプション）により、ターン間のコンテキスト キャッシュ保存を効率化し、トークン費用を削減できます。
  • 新機能のリリース: 今後、すべての新しいモデル、マルチモーダル機能、ツール、エージェント機能は Interactions API でリリースされます。

デフォルトでは、Interactions API はリクエストを保存するため、previous_interaction_id を使用してサーバーサイドの状態管理機能を利用できます。store=false を設定すると、ステートレス動作を選択できます。詳細については、データの保持をご覧ください 。

始める

機能ガイド

これらのガイドで、Interactions API の具体的な機能をご確認ください。これらのページでは、切り替えを使用して generateContent API と Interactions API を切り替えることができます。

Interactions API の仕組み

Interactions API は、コアリソースであるInteractionを中心に構成されています。Interaction は、会話またはタスクの完全なターンを表します。セッション レコードとして機能し、インタラクションの履歴全体を実行ステップ の時系列シーケンスとして含みます。これらのステップには、モデルの思考、サーバーサイドまたはクライアントサイドのツール呼び出しと結果（function_call、function_result など）、最終的な model_output が含まれます。保存されたリソース（interactions.get で取得）には、完全なコンテキストの user_input ステップも含まれますが、interactions.create レスポンスではモデル生成ステップのみが返されます。

interactions.create を呼び出すと、新しい Interaction リソースが作成されます。

サーバーサイドの状態管理

後続の呼び出しで完了したインタラクションの id を previous_interaction_id パラメータを使用して会話を続行できます。サーバーはこの ID を使用して会話履歴を取得するため、チャット履歴全体を再送信する必要はありません。

previous_interaction_id パラメータは、previous_interaction_id を使用して会話履歴（入力と出力）のみを保持します。他のパラメータはインタラクション スコープ であり、現在生成している特定のインタラクションにのみ適用されます。

  • tools
  • system_instruction
  • generation_config（thinking_level、temperature など）

つまり、これらのパラメータを適用する場合は、新しいインタラクションごとに再指定する必要があります。このサーバーサイドの状態管理は省略可能です。各リクエストで会話履歴全体を送信して、ステートレス モードで動作することもできます。

データの保存と保持

デフォルトでは、API はすべての Interaction オブジェクト（store=true）を保存して、 サーバーサイドの状態管理機能（ previous_interaction_idを使用）、バックグラウンド実行（background=trueを使用）、 オブザーバビリティを簡素化します。

  • 有料階層: インタラクションは 55 日間 保持されます。
  • 無料階層: インタラクションは 1 日間 保持されます。

これを希望しない場合は、リクエストで store=false を設定できます。この管理手段は状態管理とは別のものであり、任意のインタラクションの保存をオプトアウトできます。ただし、 store=falseはバックグラウンド実行と互換性がなく、後続のターンで previous_interaction_idを使用できなくなることに注意してください。

保存されたインタラクションは、 API リファレンスにある delete メソッドを使用していつでも削除できます。インタラクションを削除できるのは、インタラクション ID がわかっている場合のみです。

保持期間が終了すると、データは自動的に削除されます。

システムは、利用規約に従って Interaction オブジェクトを処理します。

ベスト プラクティス

  • キャッシュ ヒット率: ステートフル モードと ステートレス モードの両方で暗黙的なキャッシュ保存がサポートされています（ クイックスタートをご覧ください）。previous_interaction_id（ステートフル）を使用して会話を続行すると、会話履歴の暗黙的なキャッシュ保存をより簡単に利用できるため、パフォーマンスが向上し、コストが削減されます。
  • インタラクションの組み合わせ: 会話内でエージェントと モデルのインタラクションを柔軟に組み合わせることができます。たとえば、Deep Research エージェントなどの専門エージェントを使用して初期データ収集を行い、標準の Gemini モデルを使用して要約や再フォーマットなどのフォローアップ タスクを実行し、これらのステップを previous_interaction_id でリンクできます。

サポートされているモデルとエージェント

モデル名 タイプ モデル ID
Gemini 3.5 Flash モデル gemini-3.5-flash
Gemini 3.1 Pro プレビュー版 モデル gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite モデル gemini-3.1-flash-lite
Gemini 3 Flash プレビュー モデル gemini-3-flash-preview
Gemini 2.5 Pro モデル gemini-2.5-pro
Gemini 2.5 Flash モデル gemini-2.5-flash
Gemini 2.5 Flash-lite モデル gemini-2.5-flash-lite
Gemini 3 Pro Image モデル gemini-3-pro-image
Gemini 3.1 Flash Image モデル gemini-3.1-flash-image
Gemini 3.1 Flash TTS プレビュー モデル gemini-3.1-flash-tts-preview
Gemma 4 31B IT モデル gemma-4-31b-it
Gemma 4 26B MoE IT モデル gemma-4-26b-a4b-it
Lyria 3 Clip プレビュー モデル lyria-3-clip-preview
Lyria 3 Pro プレビュー モデル lyria-3-pro-preview
Deep Research プレビュー エージェント deep-research-preview-04-2026
Deep Research プレビュー エージェント deep-research-max-preview-04-2026
Antigravity プレビュー エージェント antigravity-preview-05-2026

SDK

Interactions API にアクセスするには、最新バージョンの Google GenAI SDK を使用します。

  • Python の場合、2.3.0 バージョン以降の google-genai パッケージです。
  • JavaScript の場合、2.3.0 バージョン以降の @google/genai パッケージです。

SDK のインストール方法について詳しくは、 ライブラリ ページをご覧ください。

制限事項

  • リモート MCP: Gemini 3 はリモート MCP をサポートしていません。近日中にサポートされる予定です。
  • マルチターン モデルの互換性: 会話で異なるモデルを組み合わせる場合（ステートフルまたはステートレス）、後続のモデルは前のモデルの出力モダリティを入力としてサポートする必要があります。たとえば、gemini-3.1-flash-image を使用して画像を生成した場合、画像入力を受け付けないモデル（テキストのみのモデルや Lyria などの音楽生成モデル）で会話を続行することはできません。

次の機能は generateContent API でサポートされていますが、Interactions API ではまだ利用できません 。

フィードバック

皆様からのフィードバックは、Interactions API の開発に不可欠です。 Google AI デベロッパー コミュニティ フォーラムで、ご意見やバグ報告、機能リクエストをお寄せください。

次のステップ