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

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

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

統合を更新するには、新しいスキーマに移行する方法の手順に沿って 操作してください。

コアの変更: outputs から steps

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

  • 以前: レスポンスは、モデルが生成したコンテンツのみを含むフラットな outputs 配列を返していました。
  • 新しいスキーマ: レスポンスは、型識別子を含む構造化されたステップを含む steps 配列を返します。

POST /interactions は出力ステップのみを返します。GET /interactions/{id} は、最初の user_input ステップを含む完全なステップ タイムラインを返します。

基本的な入出力（単項）

変更前（以前）

Python

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

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

JavaScript

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

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

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "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.5-flash", input="Tell me a joke."
)

# Response access (Recommended sugar)
print(interaction.output_text)

JavaScript

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

// Response access (Recommended sugar)
console.log(interaction.output_text);

[sdk-convenience]: /gemini-api/docs/interactions#convenience-properties

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Tell me a joke."
  }'

// POST Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

// GET /v1beta/interactions/int_123 (returns full timeline including input)
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "content": [
        { "type": "text", "text": "Tell me a joke." }
      ]
    },
    {
      "type": "model_output",
      "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

// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "thought",
      "summary": [{
        "type": "text",
        "text": "I need to check the weather in Boston..."
      }],
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'

// POST Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "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.completed
  • interaction.in_progress
  • interaction.requires_action
  • step.start
  • step.delta
  • step.stop

非推奨のイベントタイプ

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

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.completed
  • interaction.status_update → interaction.in_progress、interaction.requires_action などに置き換えられます。

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

例

変更前（以前）

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3.5-flash",
    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.5-flash',
    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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "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.5-flash",
    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.5-flash',
    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

 # Opt-in needed before May 26th
 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
   -H "Api-Revision: 2026-05-20" \
   -d '{
     "model": "gemini-3.5-flash",
     "input": "Tell me a story.",
     "stream": true
   }'

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3.5-flash"}, "event_type": "interaction.created"}
 //
 // event: interaction.in_progress
 // data: {"interaction_id": "int_xyz", "event_type": "interaction.in_progress"}
 //
 // event: step.start
 // data: {"index": 0, "step": {"type": "thought", "signature": "abc123..."}, "event_type": "step.start"}
 //
 // event: step.stop
 // data: {"index": 0, "event_type": "step.stop"}
 //
 // event: step.start
 // data: {"index": 1, "step": {"content": [{"text": "Once upon", "type": "text"}], "type": "model_output"}, "event_type": "step.start"}
 //
 // event: step.delta
 // data: {"index": 1, "delta": {"text": " a time...", "type": "text"}, "event_type": "step.delta"}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.completed
 // data: {"type": "interaction.completed", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: Dedicated completion event

ステートレスな会話履歴

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

  • 以前: デベロッパーは、レスポンスから 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 に移動します。 "type": "image" を含む response_format エントリで、aspect_ratio や image_size などの画像出力設定を指定するようになりました。

構造化出力（JSON）

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

変更前（以前）

Python

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

print(interaction.outputs[-1].text)

JavaScript

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

console.log(interaction.outputs[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "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.5-flash",
    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 response
print(interaction.output_text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3.5-flash',
    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 response
console.log(interaction.output_text);

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'

イメージの構成

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

変更前（以前）

Python

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    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.5-flash',
    input: 'Generate an image of a sunset over the ocean.',
    generation_config: {
        image_config: {
            aspect_ratio: '1:1',
            image_size: '1K'
        }
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "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.5-flash",
    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",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3.5-flash',
    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',
        aspect_ratio: '1:1',
        image_size: '1K'
    },
});

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

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

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

SDK ユーザー

最新の SDK バージョン（Python 2.0.0 以上、JavaScript 2.0.0 以上）にアップグレードします。SDK は自動的に新しいスキーマにオプトインします。レスポンスの読み取り方法を更新する以外にコードを変更する必要はありません（上記の例を参照）。これらの SDK バージョンでは、新しいスキーマのみがサポートされます。SDK の旧バージョン（Python 1.x.x、JavaScript 1.x.x）は、2026 年 6 月 8 日 に以前のスキーマが削除されるまで引き続き動作します。

REST API ユーザー

リクエストに Api-Revision: 2026-05-20 ヘッダーを追加して、新しいスキーマにオプトインします。5 月 26 日 以降、新しいスキーマがすべての リクエストのデフォルトになります。API が以前のスキーマを完全に削除する 6 月 8 日 まで、Api-Revision: 2026-05-07 で一時的にオプトアウトできます。

タイムライン

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

移行チェックリスト

steps スキーマ（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 を単一のオブジェクトから配列に変換します。