Interactions API

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

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 リソースが作成されます。

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."
  }'

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

完了したインタラクションの id を previous_interaction_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 を使用して会話履歴（入力と出力）のみを保持します。他のパラメータはインタラクション スコープ であり、現在生成している特定のインタラクションにのみ適用されます。

  • 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 を使用できなくなることに注意してください。

有料階層のプロジェクトでは、 AI Studio で保持期間を設定して、 7 日、14 日、28 日、55 日後にプロジェクト ストレージからログを自動的に削除するように設定できます。保持期間が短いと、過去の会話の取得に影響する可能性があります。

保存されたインタラクションは、 delete メソッドを使用していつでもプログラムで削除できます。 これにはインタラクション ID が必要です。AI Studio では、保存された インタラクション ログを表示して管理することもできます（プロジェクト ストレージからの削除など）。

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

Interactions オブジェクトは、利用規約に従って処理されます。

AI Studio でインタラクションを表示する

API は、有料階層のプロジェクトで store=true で実行された Interactions API リクエストを保存します。Google AI Studio の [ログ] ページから直接確認できます。詳しくは、 ログガイドをご覧ください。

ベスト プラクティス

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

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

モデル名 タイプ モデル ID
Gemini 4 Argon モデル gemini-4-argon
Gemini 3.8 Flash モデル gemini-3.8-flash
Gemini 3.6 Flash モデル gemini-3.6-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 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-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 ではまだ利用できません。

フィードバック

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

次のステップ