Geminiの公式ドキュメント、特に Nano Banana の画像生成のようなページを開くと、ページ上部に切り替えスイッチが追加されていることに気づくかもしれません。片側は Interactions API、もう片側は generateContent API です。これは単なるドキュメント改訂ではありません。Google が 2026 年 6 月に Interactions API を正式に GA（一般提供）へ押し上げ、新規プロジェクトではこちらを優先採用するよう推奨した、という大きな方針転換です。本記事では、公式ドキュメントと APIYI ゲートウェイの実測結果を踏まえ、両者の核心的な違い、機能ギャップ、実際の呼び出し指針を一気に整理します。
核心価値: この記事を読めば、Interactions API と generateContent の設計思想、状態管理、機能カバレッジの違いが明確になり、APIYI 経由で Gemini を呼び出す際にどちらのパラダイムを選ぶべきかが分かります。
Interactions API と generateContent の核心的な違い
結論から言うと、この 2 つの API は単なるバージョンアップの関係ではなく、異なる設計思想に基づいた 2 つの方式です。generateContent はステートレスな「1 リクエスト 1 レスポンス」モデルで、クライアント側が会話履歴をすべて管理する必要があります。一方、Interactions API は状態管理をサーバー側に持たせ、「Interaction」という新しい概念を中心に交互作用全体を再設計しています。
公式ドキュメントでは、1 つの Interaction を「1 回の完全な会話、またはタスクのラウンド」と定義しており、その内部は時系列に並んだ一連の実行ステップで構成されます。具体的には、モデルの思考過程、ツール呼び出しとその戻り値、そして最終的なモデル出力が含まれます。つまり、Interactions API は単発の QA だけでなく、多輪対話や agent 系タスクを最初から想定して設計されているのです。
これが、Google が単に「新機能追加」ではなく「正式可用」という言い方をした理由でもあります。Interactions API は 2025 年 12 月にベータへ入り、2026 年 6 月に正式に GA と発表されました。公式ブログには「新規プロジェクトやアプリケーションには Interactions API の使用を推奨する」と明記されており、すでにすべての公式ドキュメントでも新しいパラダイムがデフォルト表示になっています。さらに Google は、サードパーティ SDK やエコシステムのパートナーにもこれをデフォルトのインターフェースとして採用するよう促しています。要するに、これは「選べる便利機能」ではなく、Gemini の呼び出し方そのものを再定義する動きです。ただし、移行ガイドも用意されているため、開発者は自分のペースで段階的に移行でき、強制的な一斉切り替えではありません。
| 比較項目 | generateContent（legacy） | Interactions API |
|---|---|---|
| 現在の状態 | レガシーだが完全サポート | 2026年6月より正式GA |
| 公式推奨 | 既存プロジェクトは継続利用可 | 新規プロジェクトでは優先採用を推奨 |
| コアメソッド | generateContent | interactions.create / get / delete |
| 設計思想 | ステートレスな単発リクエスト | Interaction を中心とした状態管理型のタスクラウンド |
| 今後の新機能 | 引き続き主要モデルの更新対象 | 最先端の agent 機能が優先的に投入される |
🎯 技術アドバイス: APIYI apiyi.com 経由で Gemini シリーズのモデルを呼び出している場合は、まず公式ドキュメントと照らし合わせて、現在のプロジェクトがどちらのパラダイムを使っているのかを数分で確認するのがおすすめです。そのうえで移行が必要か判断すれば、ドキュメント上で Interactions API がデフォルト表示されていることを見て、既存コードまで古いと勘違いするのを避けられます。
リクエスト方式と状態管理：2つのパラダイムの本質的な違い
2つの違いを理解する鍵は、「対話履歴を誰が管理するのか」です。generateContent では、クライアントが毎回、対話履歴のメッセージ配列を完全に組み立てて送る必要があります。たとえ10ターン目の会話でも、最初から9ターン分の内容をそのまま含めなければなりません。この方式はシンプルで分かりやすい一方、会話が長くなるほどリクエスト本文がどんどん大きくなり、重複して送った履歴分も繰り返し課金されます。
Interactions API は、この問題に対する解法を提供します。前回の呼び出しで返された interaction id を、次回リクエストの previous_interaction_id パラメータとして渡すだけで、サーバー側が対話履歴全体を自動で復元してくれます。クライアント側で履歴を手動で結合し直したり、再送したりする必要はありません。公式ドキュメントでは、長時間かかるタスク向けの background=true パラメータや、「observable execution steps」によってモデルの途中思考をデバッグやフロントエンドUIに表示できる機能も案内されており、agent 系のプロダクトを作るうえで特に価値があります。
ただし、サーバー側の状態管理には代償もあります。デフォルトでは store パラメータが true になっており、システムは interaction レコードを保持します。課金アカウントでは55日、無料アカウントでは1日保存されます。もしプライバシーやコンプライアンスの理由で store を false にすると、保存は無効化できますが、同時に previous_interaction_id による会話継続とバックグラウンド実行の2つの機能も使えなくなります。ここは事前にしっかり比較検討すべきポイントです。
コスト面でも、公式は明確な価値を示しています。サーバー側で状態を管理すれば、同じ会話の履歴を毎回入力 token として再計上する必要がなくなり、キャッシュヒット率が大きく向上します。公式の表現を借りれば、「より低コストで、より高いキャッシュヒット率」です。カスタマーサポート向けボットや長文ドキュメントQAのように、長いコンテキストを維持する必要がある場面では、この差は呼び出し回数が増えるほどはっきり効いてきます。一方で、単発生成やバッチ処理のような、もともとステートレスなタスクでは、このコスト優位性はほとんど活きません。
見落としやすい点として、 tools、system_instruction、generation_config（thinking_level や temperature などを含む）といったパラメータは「都度指定」です。previous_interaction_id で前回の対話を引き継いでも、これらの設定は自動継承されません。毎回、明示的に再指定する必要があります。
| 機能項目 | generateContent | Interactions API |
|---|---|---|
| 対話履歴の管理 | クライアントが全履歴を手動で結合 | サーバーが previous_interaction_id で自動取得 |
| 長時間タスクのバックグラウンド実行 | 非対応 | background=true をサポート |
| 中間実行ステップの可視性 | 自前で解析が必要 | observable execution steps を提供 |
| レコード保持ポリシー | 概念なし | デフォルトで保持、課金55日/無料1日 |
| ツールと生成パラメータの継承 | 毎回明示的に指定 | 毎回明示的に指定、自動継承なし |
💡 選び方の सुझाव: 頻繁にマルチターン対話を行う、または agent ワークフローを構築するプロジェクトでは、Interactions API の状態管理機構によって、面倒な接着コードをかなり減らせます。ただし、主な用途が単発生成であれば、そのメリットはあまり目立たないかもしれません。APIYI apiyi.com のプラットフォームで小規模トラフィックの比較テストを行ってから、移行する価値があるか判断するのがおすすめです。
両者の能力ギャップ：何ができて、何がまだできないのか
Interactions API は新しいパラダイムですが、公式ドキュメントでは現在まだ未対応の機能も明記されています。選定時にはこの点も必ず考慮しなければならず、「新しいからより万能」とは考えないほうがいいです。
公式には、Interactions API は現時点で動画理解における video metadata フィールド、Batch API、Python の automatic function calling、そして explicit caching をまだサポートしていないと書かれています。ただし、previous_interaction_id を使った implicit caching は利用できます。これに対して generateContent は、ストリーミング出力、関数呼び出し、Batch API、explicit caching に加え、テキスト、画像、音声、動画、ドキュメントを含む完全なマルチモーダル入力をサポートしています。
| 機能 | generateContent | Interactions API |
|---|---|---|
| Batch API | ✅ 対応 | ❌ まだ非対応 |
| 明示的キャッシュ（explicit caching） | ✅ 対応 | ⚠️ implicit caching のみ |
| 動画 metadata フィールド | ✅ 対応 | ❌ まだ非対応 |
| Python 自動関数呼び出し | ✅ 対応 | ❌ まだ非対応 |
| ストリーミング出力 / 関数呼び出し | ✅ 対応 | ✅ 対応 |
| コストとキャッシュヒット率の主張 | 通常課金 | 公式は低コスト・高ヒット率と主張 |
Nano Banana の画像生成という具体的なシーンで見ると、2つのパラダイムの違いは結果の取り出し方に最もはっきり表れます。Interactions API では interaction.output_image や interaction.output_text のような便利なプロパティで、最後に生成された画像やテキストブロックを直接取得できます。一方、generateContent では candidates[0].content.parts 配列を下からたどる必要があり、各 part の型を自分で判定しなければなりません。すでに generateContent 用の解析ロジックを書いているプロジェクトでは、この構造差は単なるエンドポイント変更では済まない、大きめの改修になることが多いです。
これらの不足は、決して些細な機能差ではありません。Batch API は、コスト重視のプロジェクトがオフライン処理をまとめて実行する際の中核的な手段です。もし移行後に新しいパラダイムで使えないとなると、オフライン処理全体を再設計し直す必要があります。明示的キャッシュも、長いコンテキストを扱う場面でのコストに直結します。業務の中で、大きな固定の system prompt や参照資料を何度も使い回すなら、explicit caching がないと、どの内容をどれだけ、どのくらいの期間キャッシュするかを細かく制御できません。だからこそ公式ドキュメントは generateContent の系統をすぐに退役させず、2本立ての技術路線を残しているのです。少なくとも、これらの機能が埋まるまでは、generateContent は代替不能と言えるでしょう。
🔧 実践アドバイス: もし業務が Batch API による一括処理や、explicit caching を使ったコスト削減に強く依存しているなら、今の段階で急いで Interactions API に切り替えると、必要な機能を失う可能性があります。公式の移行ガイドがどう更新されるかをしばらく見守り、すぐに本番コードを置き換えないほうが安全です。
APIYI ゲートウェイ実測：いま使うべきパラダイムはどれか
結論を先に言うと、2026年7月4日時点の実測では、APIYI ゲートウェイ経由で Gemini を呼び出す場合は、引き続き generateContent のネイティブ形式を使うべきです。
APIYI 技術チームは Interactions API の重要な経路について直接テストを行い、2つの主流な認証方式を網羅しました。結果は以下のとおりです。
| テストエンドポイント | 認証方式 | 結果 |
|---|---|---|
| POST /v1beta2/interactions | Bearer token | ❌ 404（Invalid URL） |
| POST /v1beta/interactions | Bearer token | ❌ 404（Invalid URL） |
| POST /v1beta2/interactions | x-goog-api-key header | ❌ 404（Invalid URL） |
| POST /v1beta/models/{model}:generateContent | Bearer token | ✅ 正常に返却 |
APIYI 公式ドキュメントの原文でも、「APIYI ゲートウェイは現時点で Interactions API の中継をサポートしていない——/v1beta2/interactions と /v1beta/interactions の両パスはいずれも 404 を返す」と明記されており、さらに明確な推奨として「APIYI 経由で Gemini を呼び出す場合は、引き続き generateContent のネイティブ形式を使用してください」と案内されています。これが、APIYI साइट内の Gemini 関連ドキュメントがすべて generateContent 形式で統一されている理由でもあります。こうしておけば、読者はコードをそのままコピーするだけで動かせて、パスの 404 に悩まされることがありません。
強調しておきたいのは、これは動的な状態であって、永久的な制限ではないという点です。Interactions API が徐々に公式のデフォルトパラダイムになっていくのに合わせて、ゲートウェイ側も今後サポートを追随していく可能性が高いでしょう。その際は APIYI が対応ドキュメントを更新します。最新の対応状況は docs.apiyi.com/api-capabilities/gemini/interactions-api のページで確認できます。毎回自分でエンドポイントをテストしなくても大丈夫です。
このテスト結果は、見落としやすい現実も示しています。公式ドキュメント上で「正式に利用可能」であることと、特定の中継ゲートウェイやサードパーティ SDK がすでに適応済みであることは、まったく別の話です。開発者が公式ドキュメントのデフォルト表示だけを見て、Interactions API のコード例をそのまま既存の中継設定に入れると、まず 404 にぶつかり、その後で「自分のコードが間違っているのか、それともゲートウェイ側がまだ追随していないのか」を切り分けるのに時間を取られがちです。こうした場合は、まず自分の呼び出し経路（公式への直結か、第三者経由の中継か）が新しいパラダイムに対応しているかを確認するほうが、業務コードを何度も見直すより早く問題を特定できます。
🚀 クイックスタート: いますぐ Gemini の呼び出し経路が正常か確認したいなら、APIYI apiyi.com の generateContent 形式で接続するのがおすすめです。統一された base_url が用意されており、テキストや画像など複数の Gemini モデル呼び出しに対応しているので、認証まわりを追加で処理する必要はありません。
どう選ぶか：シナリオ別の判断ガイド
前述の機能比較と実測結果を踏まえて、シンプルなシナリオ別の推奨表をまとめます。
| 使用シーン | 推奨方案 | 理由 |
|---|---|---|
| APIYI ゲートウェイ経由で Gemini を呼び出す | generateContent | 現在ゲートウェイがこの形式のみ対応しており、Interactions API のパスは 404 を返すため |
| Batch API による一括処理が必要 | generateContent | Interactions API は現時点で Batch API に未対応 |
| 明示的キャッシュでコストを下げたい | generateContent | Interactions API は現時点では暗黙キャッシュのみ |
| 複数ターン対話の agent を構築し、公式 API に直結する | Interactions API を検討可 | サーバー側の状態管理により履歴をつなぐロジックを省けるため |
| モデルの中間実行ステップを観察してデバッグしたい | Interactions API | observable execution steps をネイティブにサポート |
| 既存プロジェクトがすでに generateContent で安定稼働している | すぐには移行しない | legacy も完全対応しており、短期的には新モデルも引き続き利用できるため |
要するに、移行するかどうかは「新しいかどうか」ではなく、自分の依存関係が Interactions API にどこまで完全対応しているか、そして Gemini の呼び出し経路が（公式直結なのか中継ゲートウェイ経由なのか）いま新しいパラダイムをサポートしているかで決まります。APIYI 経由で中継して使う開発者の多くにとっては、現時点では generateContent を維持するほうが、より安全で確実な選択です。
よくある質問
Q1: generateContent は終了されますか？今から新規プロジェクトをこれに基づいて開発する価値はありますか？
短期的には終了しません。公式は generateContent を legacy としてマークしているものの、「引き続き完全にサポートされる」と明言しており、今後予見できる範囲でも新しい本流の Gemini モデルは継続して追加される見込みです。APIYI apiyi.com 経由で Gemini を呼び出す場合、現時点では generateContent ベースで新規プロジェクトを開発してもまったく問題ありません。ドキュメントの初期表示が Interactions API だからといって、焦る必要はありません。
Q2: APIYI のゲートウェイはいつ Interactions API に対応しますか？
現時点では明確なスケジュールはありません。これは、このパラダイムが公式エコシステムでどれだけ普及するか、またゲートウェイ側の対応がどの程度進むかに左右されます。APIYI apiyi.com プラットフォームの公式ドキュメント更新を確認するのがおすすめです。Interactions API の中継に対応した場合は、関連ドキュメントがすぐに更新されるため、エンドポイントの状態を自分で何度も試す必要はありません。
Q3: 2つの API を同じプロジェクト内で併用できますか？
技術的には、呼び出し経路が対応していれば 2 つのパラダイムを共存させることは可能です。たとえば、generateContent で Batch API のバッチ処理を行いながら、公式 API に直接接続するマルチターン対話のシナリオでは Interactions API を試す、といった使い分けができます。ただし APIYI ゲートウェイ経由では、現状 Interactions API のパスが 404 を返すため、当面は generateContent 形式に統一することをおすすめします。同じプロジェクト内で 2 系統の異なる呼び出しロジックが混在すると、保守コストが増えてしまうためです。
まとめ
Interactions API は 2026 年 6 月に正式版となり、Google が Gemini の呼び出し方法として長期的に重視している方向性を示しています。サーバー側での状態管理や、実行ステップを可観測にできる点は agent 系アプリケーションにとって非常に魅力的です。一方で、Batch API、明示的なキャッシュ、動画 metadata などではまだ明確な不足があり、generateContent は引き続き完全サポートされ、短期的にも継続して更新されます。さらに重要なのは、APIYI ゲートウェイ経由で Gemini を呼び出す場合、現時点の実測では Interactions API 関連のパスはすべて 404 を返しており、generateContent だけが現在利用可能な形式だという点です。Gemini シリーズのモデルを安定的かつ確実に呼び出したい場合は、APIYI apiyi.com を通じて generateContent のネイティブ形式で接続することをおすすめします。ゲートウェイが新しいパラダイムに対応次第、ドキュメントも速やかに更新されます。
この記事の実測データと公式情報の確認は、すべて APIYI 技術チームが担当しました。Gemini シリーズのモデル呼び出しの詳細を知りたい方は、APIYI apiyi.com からお気軽にサポートへお問い合わせください。
参考資料
-
Google AI for Developers – Interactions API の概要: Interaction の概念、コアメソッド、機能の説明
- リンク：
ai.google.dev/gemini-api/docs/interactions-overview
- リンク：
-
Google AI for Developers – generateContent（Legacy）: レガシー API のサポート状況と対応範囲
- リンク：
ai.google.dev/gemini-api/docs/interactions
- リンク：
-
APIYI 公式ドキュメント – Gemini Interactions API の対応状況: ゲートウェイでの実測エンドポイント結果と呼び出しの推奨事項
- リンク：
docs.apiyi.com/api-capabilities/gemini/interactions-api
- リンク：
