Gemini Deep Research がプレビュー版で利用可能になりました。共同プランニング、可視化、MCP サポートなどが含まれています。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Interactions API: 破壊的変更の移行ガイド（2026 年 5 月）

v1beta Interactions API には、API の形状を再構築して、飛行中のステアリングや非同期ツール呼び出しなどの今後の機能をサポートするための破壊的変更が導入されています。このページでは、変更点について説明し、移行に役立つように変更前後のコード例を示します。変更には次の 2 つのカテゴリがあります。

ステップスキーマ: 新しい steps 配列が outputs 配列に代わり、各インタラクションターンの構造化されたタイムラインを提供します。
出力形式の構成: 新しいポリモーフィック response_format により、すべての出力形式の制御が統合され、response_mime_type が削除されます。

新しいスキーマに移行する方法の手順に沿って、統合を更新します。

コアの変更: `outputs` から `steps`

新しいスキーマでは、outputs 配列が steps 配列に置き換えられます。

以前: レスポンスは、モデルの生成コンテンツのみを含むフラットな outputs 配列を返していました。
新しいスキーマ: レスポンスは、エコーされたユーザー入力とモデル出力の両方を含む steps 配列を返します。これにより、インタラクションターンの完全なタイムラインが提供されます。

単項（非ストリーミング）レスポンスは、steps 配列の最初のステップとして入力をエコーバックします。ストリーミングレスポンスでは、入力ステップがスキップされ、生成されたコンテンツの差分のみが出力されます。

基本的な入出力（単項）

以前（従来版）

Python

# Request
interaction = client.interactions.create(
    model="gemini-3-flash-preview", input="Tell me a joke."
)

# Response access
print(interaction.outputs[0].text)

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "role": "model",
  "outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]
}

変更後（新しいスキーマ）

Python

# Request
interaction = client.interactions.create(
    model="gemini-3-flash-preview", input="Tell me a joke."
)

# Response access
print(interaction.steps[-1].content[0].text)  # CHANGED: steps instead of outputs

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

関数呼び出し

リクエストの構造は変更されませんが、レスポンスではフラットな outputs コンテンツが構造化されたステップに置き換えられます。

以前（従来版）

Python

# Accessing function call in legacy schema
for output in interaction.outputs:
    if output.type == "function_call":
        print(f"Calling {output.name} with {output.arguments}")

JavaScript

// Accessing function call in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'function_call') {
        console.log(`Calling {output.name} with {JSON.stringify(output.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  "outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

変更後（新しいスキーマ）

Python

# Accessing function call in new steps schema
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Calling {step.name} with {step.arguments}")

JavaScript

// Accessing function call in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'function_call') {
        console.log(`Calling {step.name} with {JSON.stringify(step.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "What's the weather in Boston?" }
      ]
    },
    {
      "type": "thought",
      "status": "done",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "status": "waiting",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

サーバーサイドツール

サーバーサイドツール（Google 検索やコード実行など）は、steps 配列で特定のステップタイプを生成するようになりました。以前のスキーマでは、これらのオペレーションは outputs 配列内の特定のコンテンツタイプとして返されていましたが、新しいスキーマでは steps 配列に移動されています。次の例では、Google 検索を使用します。

以前（従来版）

Python

# Accessing search results in legacy schema
for output in interaction.outputs:
    if output.type == "google_search_call":
        print(f"Searched for: {output.arguments.queries}")
    elif output.type == "google_search_result":
        print(f"Found results: {output.result.rendered_content}")

JavaScript

// Accessing search results in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'google_search_call') {
        console.log(`Searched for: {output.arguments.queries}`);
    } else if (output.type === 'google_search_result') {
        console.log(`Found results: {output.result.renderedContent}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "outputs": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] }
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "rendered_content": "<div>...</div>",
        "url": "https://www.nfl.com/super-bowl"
      }
    },
    {
      "type": "text",
      "text": "The Kansas City Chiefs won the last Super Bowl.",
      "annotations": [
        {
          "start_index": 4,
          "end_index": 22,
          "source": "https://www.nfl.com/super-bowl"
        }
      ]
    }
  ],
  "status": "completed"
}

変更後（新しいスキーマ）

Python

# Accessing search results in new steps schema
for step in interaction.steps:
    if step.type == "google_search_call":
        print(f"Searched for: {step.arguments.queries}")
    elif step.type == "google_search_result":
        print(f"Found results: {step.result.search_suggestions}")

JavaScript

// Accessing search results in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'google_search_call') {
        console.log(`Searched for: {step.arguments.queries}`);
    } else if (step.type === 'google_search_result') {
        console.log(`Found results: {step.result.searchSuggestions}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "Who won the last Super Bowl?" }
      ]
    },
    {
      "type": "google_search_call",
      "status": "done",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "status": "done",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "The Kansas City Chiefs won the last Super Bowl.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.nfl.com/super-bowl",
              "title": "NFL.com",
              "start_index": 4,
              "end_index": 22
            }
          ]
        }
      ]
    }
  ],
  "status": "completed"
}

ストリーミング

ストリーミングでは、新しいイベントタイプが公開されます。

新しいイベントタイプ

interaction.created
interaction.status_update - 完了やエラーを含むすべてのライフサイクル状態をカバーするようになりました（下記のステータスを参照）。
step.start
step.delta
step.stop

`interaction.status_update` 件のステータス

in_progress
active
completed
interrupted
requires_action
error

非推奨のイベントタイプ

次の以前のイベントタイプは、上記の新しいイベントに置き換えられます。

interaction.start → interaction.created
content.start → step.start
content.delta → step.delta
content.stop → step.stop
interaction.complete → interaction.status_update（status: "completed" を含む）
error → interaction.status_update（status: "error" を含む）
interaction.status_update → interaction.status_update（変更なし。ただし、追加の状態をカバーするようになりました）

ストリーミング関数呼び出し: 関数呼び出しでストリーミングを使用する場合、step.start イベントは関数名を配信し、step.delta イベントは引数を部分的な JSON 文字列としてストリーミングします（arguments_delta を使用）。これらのデルタを累積して、完全な引数を取得する必要があります。これは、完全な関数呼び出しオブジェクトを一度に受け取る単項呼び出しとは異なります。

例

変更前（従来版）

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)

JavaScript

// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Explain quantum entanglement in simple terms.',
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        }
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Explain quantum entanglement in simple terms.",
  "stream": true
}

// Response (SSE Lines)
// event: interaction.start
// data: {"id": "int_123", "status": "in_progress"}
//
// event: content.start
// data: {"index": 0, "type": "text"}
//
// event: content.delta
// data: {"delta": {"type": "text", "text": "Quantum entanglement is..."}}
//
// event: content.stop
// data: {"index": 0}
//
// event: interaction.complete
// data: {"id": "int_123", "status": "done", "usage": {"total_tokens": 42}}

変更後（新しいスキーマ）

Python

# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a story.",
    stream=True,
):
    if event.type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")

JavaScript

// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.type === 'step.delta') {  // CHANGED: step.delta instead of content.delta
        if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    }
}

REST

 // Request: POST /v1beta/interactions
 // Accept: text/event-stream
 {
   "model": "gemini-3-flash-preview",
   "input": "Tell me a story."
 }

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"type": "interaction.created", "interaction": {"id": "int_xyz", "status": "created"}} // CHANGED: 'type' instead of 'event_type'
 //
 // event: interaction.status_update
 // data: {"type": "interaction.status_update", "status": "in_progress"} // NEW: Lifecycle status updates in stream (postpone until Sessions launch dependency)
 //
 // event: step.start
 // data: {"type": "step.start", "index": 0, "step": {"type": "thought"}} // NEW: Replaces content.start, 'step' instead of 'content'
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 0, "delta": {"type": "thought", "text": "User wants an explanation."}} // NEW: Delta type matches step type
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 0, "status": "done"} // NEW: Includes status
 //
 // event: step.start
 // data: {"type": "step.start", "index": 1, "step": {"type": "model_output"}} // NEW: Step wrapper for output
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 1, "delta": {"type": "text", "text": "Hello"}}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.complete
 // data: {"type": "interaction.complete", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: End of stream event with interaction details

ステートレスの会話履歴

クライアント側で会話履歴を手動で管理している場合（ステートレスのユースケース）、以前のターンを連結する方法を更新する必要があります。

以前の動作: デベロッパーは、レスポンスから outputs 配列を収集し、次のターンで input フィールドで返送していました。
新しいスキーマ: レスポンスから steps 配列を収集し、次のリクエストの input フィールドに渡して、新しいユーザーターンを user_input ステップとして追加する必要があります。

出力形式の構成: `response_format` の変更

更新された API では、すべての出力形式制御が統合されたポリモーフィック response_format フィールドに統合されています。これにより、出力構成が最上位レベルで一元化され、generation_config はモデルの動作（Temperature、Top-P、思考モードなど）に集中できます。

主な変更点

API は response_mime_type を削除します。response_format 内の形式エントリごとに MIME タイプを指定するようになりました。
response_format はポリモーフィックオブジェクト（または配列）になりました。各エントリには、type 判別子（text、audio、image）と型固有のフィールドがあります。複数の出力モードをリクエストするには、形式エントリの配列を渡します。
image_config が generation_config から response_format に移動します。aspect_ratio や image_size などの画像出力設定は、"type": "image" を含む response_format エントリで指定するようになりました。

構造化出力（JSON）

新しいスキーマでは response_mime_type フィールドが削除されています。代わりに、"type": "text" を使用して response_format オブジェクト内に MIME タイプと JSON スキーマを指定します。

以前（従来版）

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    response_mime_type="application/json",
    response_format={
        "type": "object",
        "properties": {
            "summary": {"type": "string"}
        }
    },
)

print(interaction.outputs[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    responseMimeType: 'application/json',
    responseFormat: {
        type: 'object',
        properties: {
            summary: { type: 'string' }
        }
    },
});

console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  "response_mime_type": "application/json",
  "response_format": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" }
    }
  }
}

変更後（新しいスキーマ）

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    # response_mime_type is removed — specify mime_type inside response_format
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"}
            }
        }
    },
)

print(interaction.steps[-1].content[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    // responseMimeType is removed — specify mimeType inside responseFormat
    responseFormat: {
        type: 'text',
        mimeType: 'application/json',
        schema: {
            type: 'object',
            properties: {
                summary: { type: 'string' }
            }
        }
    },
});

console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  // response_mime_type is removed
  "response_format": {
    "type": "text",                          // NEW: type discriminator
    "mime_type": "application/json",          // MOVED: from response_mime_type
    "schema": {                              // RENAMED: was response_format directly
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }
}

イメージの構成

新しいスキーマでは、generation_config から image_config が削除されています。"type": "image" を使用して response_format エントリで画像出力設定を指定するようになりました。

以前（従来版）

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    generation_config={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "1K"
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    generationConfig: {
        imageConfig: {
            aspectRatio: '1:1',
            imageSize: '1K'
        }
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Generate an image of a sunset over the ocean.",
  "generation_config": {
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }
}

変更後（新しいスキーマ）

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    # image_config is removed from generation_config — use response_format
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "delivery": "inline",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    // imageConfig is removed from generationConfig — use responseFormat
    responseFormat: {
        type: 'image',
        mimeType: 'image/jpeg',
        delivery: 'inline',
        aspectRatio: '1:1',
        imageSize: '1K'
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Generate an image of a sunset over the ocean.",
  // image_config removed from generation_config
  "response_format": {
    "type": "image",                         // NEW: type discriminator
    "mime_type": "image/jpeg",
    "delivery": "inline",
    "aspect_ratio": "1:1",                   // MOVED: from generation_config.image_config
    "image_size": "1K"                       // MOVED: from generation_config.image_config
  }
}

複数の出力モダリティ（テキストと音声など）を同時にリクエストするには、単一のオブジェクトではなく、形式エントリの配列を response_format に渡します。

新しいスキーマに移行する方法

SDK ユーザー

最新の SDK バージョン（Python ≥1.76.0、JavaScript ≥1.53.0）にアップグレードします。SDK は新しいスキーマを自動的に有効にします。レスポンスの読み取り方法を更新する以外にコードを変更する必要はありません（上記の例を参照）。これらの SDK バージョンでは、新しいスキーマのみがサポートされます。古い SDK バージョン（Python ≤1.73.1、JavaScript ≤1.50.1）は、2026 年 6 月 6 日に従来のスキーマが削除されるまで引き続き機能します。

REST API ユーザー

リクエストに Api-Revision: 2026-05-20 ヘッダーを追加して、新しいスキーマを今すぐ有効にしてください。5 月 20 日以降、新しいスキーマがすべてのリクエストのデフォルトになります。6 月 6 日までは、Api-Revision: 2026-05-06 を使用して一時的にオプトアウトできます。この日以降は、API によってレガシースキーマが完全に削除されます。

タイムライン

日付	フェーズ	SDK ユーザー	REST API ユーザー
5 月 6 日	オプトイン	新しいメジャー SDK バージョンが利用可能（Python ≥2.0.0、JS ≥2.0.0）。アップグレードすると、新しいスキーマが自動的に取得されます。	`Api-Revision: 2026-05-20` ヘッダーを追加してオプトインします。デフォルトはレガシーのままです。
5 月 20 日	デフォルトの反転	すでにアップグレード済みの場合は、対応は不要です。古い SDK（Python 1.x.x、JS 1.x.x）は引き続き機能しますが、以前のレスポンスを返します。	新しいスキーマがデフォルトになりました。オプトアウトするには、`Api-Revision: 2026-05-06` ヘッダーを送信します。
6 月 6 日	夕暮れ	Python と JS の 1.x.x SDK バージョンでは、Interactions API 呼び出しが失敗します。	Interactions API の従来のスキーマが削除されました。`Api-Revision` ヘッダーは無視されます。

移行チェックリスト

歩数スキーマ（`steps`）

outputs ではなく steps 配列からレスポンスコンテンツを読み取るようにコードを更新します。例を見る。
コードで user_input と model_output の両方のステップタイプが処理されることを確認します。例を見る。
（関数呼び出し）steps 配列で function_call ステップを見つけるようにコードを更新します。例を見る。
（サーバーサイドツール）ツール固有の手順（google_search_call、google_search_result など）を処理するようにコードを更新します。例をご覧ください。
（ステートレス履歴）履歴管理を更新して、次のリクエストの input フィールドに steps 配列を渡します。詳細
（ストリーミングのみ）新しい SSE イベントタイプ（interaction.created、step.delta など）をリッスンするようにクライアントを更新します。例を見る。

出力形式の構成（`response_format`）

response_mime_type を response_format 内の mime_type フィールドに置き換えます。例を見る。
既存の response_format JSON スキーマを {"type": "text", "schema": ...} オブジェクトでラップします。例を見る。
（画像生成）image_config を generation_config から response_format の {"type": "image", ...} エントリに移動します。例を見る。
（マルチモーダル）複数の出力モードをリクエストするときに、response_format を単一のオブジェクトから配列に変換します。

Interactions API: 破壊的変更の移行ガイド（2026 年 5 月）

コアの変更: outputs から steps

基本的な入出力（単項）

以前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

関数呼び出し

以前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

サーバーサイド ツール

以前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

ストリーミング

新しいイベントタイプ

interaction.status_update 件のステータス

非推奨のイベントタイプ

例

変更前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

ステートレスの会話履歴

出力形式の構成: response_format の変更

主な変更点

構造化出力（JSON）

以前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

イメージの構成

以前（従来版）

Python

JavaScript

REST

変更後（新しいスキーマ）

Python

JavaScript

REST

新しいスキーマに移行する方法

SDK ユーザー

REST API ユーザー

タイムライン

移行チェックリスト

歩数スキーマ（steps）

出力形式の構成（response_format）

コアの変更: `outputs` から `steps`

サーバーサイドツール

`interaction.status_update` 件のステータス

出力形式の構成: `response_format` の変更

歩数スキーマ（`steps`）

出力形式の構成（`response_format`）