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 を設定すると、ステートレス動作を有効にできます。詳細については、データの保持をご覧ください。
始める
- コーディング エージェントを設定する: Gemini Docs MCP に接続し、
gemini-api-devスキルをインストールして、アシスタントが最新のデベロッパー ドキュメントとベスト プラクティスに直接アクセスできるようにします。詳しい手順については、コーディング エージェントの設定ガイドをご覧ください。 generateContentから移行する: 既存の統合がある場合は、移行ガイドに沿って Interactions API に移行します。- スタートガイド: Interactions API スタートガイドの手順に沿って操作します。
機能ガイド
これらのガイドで、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 リソースが作成されます。
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Tell me a short story about a time-traveling lighthouse."
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI();
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
input: "Tell me a short story about a time-traveling lighthouse.",
});
console.log(interaction.output_text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"input": "Tell me a short story about a time-traveling lighthouse."
}'
サーバーサイドの状態管理
previous_interaction_id パラメータを使用して、完了したインタラクションの id を後続の呼び出しで使用し、会話を続けることができます。サーバーはこの ID を使用して会話履歴を取得するため、チャット履歴全体を再送信する必要がなくなります。
Python
from google import genai
client = genai.Client()
# 1. First turn
turn1 = client.interactions.create(
model="gemini-3.8-flash",
input="Hi, my name is Phil."
)
# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
model="gemini-3.8-flash",
input="What is my name?",
previous_interaction_id=turn1.id
)
print(turn2.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI();
// 1. First turn
const turn1 = await client.interactions.create({
model: "gemini-3.8-flash",
input: "Hi, my name is Phil.",
});
// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
model: "gemini-3.8-flash",
input: "What is my name?",
previous_interaction_id: turn1.id,
});
console.log(turn2.output_text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
// 1. First turn
Interaction turn1 =
client
.interactions
.create(
CreateInteractionRequestBody.of(
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("Hi, my name is Phil."))
.build()))
.interaction()
.get();
// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
client
.interactions
.create(
CreateInteractionRequestBody.of(
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("What is my name?"))
.previousInteractionId(turn1.id().get())
.build()))
.interaction()
.get();
System.out.println(turn2.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// 1. First turn
turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
}),
})
if err != nil {
log.Fatal(err)
}
// 2. Second turn (chained using PreviousInteractionID)
turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("What is my name?"),
PreviousInteractionID: turn1.Interaction.ID,
}),
})
if err != nil {
log.Fatal(err)
}
if turn2.Interaction.OutputText != nil {
fmt.Println(*turn2.Interaction.OutputText)
}
}
REST
# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"input": "What is my name?",
"previous_interaction_id": "PREVIOUS_INTERACTION_ID"
}'
previous_interaction_id パラメータは、previous_interaction_id を使用して会話履歴（入力と出力）のみを保持します。他のパラメータはインタラクション スコープであり、現在生成している特定のインタラクションにのみ適用されます。
toolssystem_instructiongeneration_config（thinking_level、temperatureなどを含む）
つまり、これらのパラメータを適用する場合は、新しいインタラクションごとに再指定する必要があります。このサーバーサイドの状態管理は省略可能です。各リクエストで完全な会話履歴を送信して、ステートレス モードで動作することもできます。
データ ストレージと保持
デフォルトでは、API はすべての Interaction オブジェクト（store=true）を保存します。これは、サーバーサイドの状態管理機能（previous_interaction_id を使用）、バックグラウンド実行（background=true を使用）、オブザーバビリティの目的での使用を簡素化するためです。
- 有料プラン: システムはインタラクションを 55 日間保持します。
- 無料枠: システムはインタラクションを 1 日間保持します。
この動作を希望しない場合は、リクエストで store=false を設定できます。このコントロールは状態管理とは別のもので、あらゆるインタラクションでストレージをオプトアウトできます。ただし、store=false はバックグラウンド実行と互換性がなく、以降のターンで previous_interaction_id を使用できなくなります。
有料ティアのプロジェクトでは、AI Studio で保持期間を構成して、7 日、14 日、28 日、55 日後にプロジェクト ストレージから削除するログを自動的にマークできます。保持期間を短くすると、過去の会話の取得に影響する可能性があります。
保存されたインタラクションは、インタラクション ID を必要とする delete メソッドをプログラムで使用して、いつでも削除できます。AI Studio では、保存されたインタラクション ログの表示と管理（プロジェクト ストレージからの削除など）も行えます。
保持期間が終了すると、データは自動的に削除されます。
インタラクション オブジェクトは、条件に従って処理されます。
AI Studio でインタラクションを表示する
API は、有料ティアのプロジェクトで store=true を使用して実行された Interactions API リクエストを保存します。Google AI Studio の [ログ] ページで直接確認できます。詳細については、ログガイドをご覧ください。
ベスト プラクティス
- キャッシュ ヒット率: 暗黙的なキャッシュ保存は、ステートフル モードとステートレス モードの両方でサポートされています（クイックスタートをご覧ください）。
previous_interaction_id（ステートフル）を使用して会話を継続すると、システムは会話履歴の暗黙的なキャッシュ保存をより簡単に利用できるようになり、パフォーマンスが向上し、費用が削減されます。 - インタラクションの組み合わせ: 会話内でエージェントとモデルのインタラクションを柔軟に組み合わせることができます。たとえば、初期データ収集に Deep Research エージェントなどの特殊なエージェントを使用し、要約や再フォーマットなどのフォローアップ タスクに標準の Gemini モデルを使用して、これらの手順を
previous_interaction_idでリンクできます。
サポートされているモデルとエージェント
| モデル名 | タイプ | モデル ID |
|---|---|---|
| Gemini 3.8 Flash | モデル | gemini-3.8-flash |
| Gemini 3.7 Flash | モデル | gemini-3.7-flash |
| Gemini 3.6 Flash | モデル | gemini-3.6-flash |
| Gemini 3.5 Flash | モデル | gemini-3.5-flash |
| Gemini 3.1 Pro プレビュー版 | モデル | gemini-3.1-pro-preview |
| Gemini 3.5 Flash-Lite | モデル | gemini-3.5-flash-lite |
| 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.5 | モデル | lyria-3.5 |
| Lyria 3 クリップのプレビュー | モデル | 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-09-2026 |
SDK
Interactions API にアクセスするには、最新バージョンの Google GenAI SDK を使用します。
- Python では、これは
2.3.0バージョン以降のgoogle-genaiパッケージです。 - JavaScript の場合、これは
2.3.0バージョン以降の@google/genaiパッケージです。 - Go では、これは
google.golang.org/genaiパッケージです。 - Java では、これは
com.google.genai:google-genaiパッケージです。
SDK のインストール方法について詳しくは、ライブラリ ページをご覧ください。
制限事項
- リモート MCP: Gemini 3 はリモート MCP をサポートしていません。近日中にサポート予定です。
- マルチターン モデルの互換性: 会話で異なるモデルを混在させる場合（ステートフルまたはステートレス）、後続のモデルは、前のモデルの出力モダリティを入力としてサポートする必要があります。たとえば、
gemini-3.1-flash-imageを使用して画像を生成した場合、画像入力を受け付けないモデル（テキストのみのモデルや、Lyria などの音楽生成モデルなど）で会話を続けることはできません。
次の機能は generateContent API でサポートされていますが、Interactions API ではまだ利用できません。
- Batch API
- 自動関数呼び出し（Python）
- 明示的なキャッシュ保存: サーバーサイドの暗黙的なキャッシュ保存は、
previous_interaction_idを介して Interactions API で利用できます。 - 安全性設定: Interactions API では、カスタムの安全性設定はサポートされていません。
フィードバック
皆様からのフィードバックは、Interactions API の開発に不可欠です。ご意見やバグの報告、機能のリクエストについては、Google AI デベロッパー コミュニティ フォーラムをご利用ください。
次のステップ
- Interactions API クイックスタート ノートブックをお試しください。
- Gemini Deep Research エージェントの詳細を確認する。