パートナーとライブラリの統合

このガイドでは、Gemini API の上にライブラリ、プラットフォーム、ゲートウェイを構築するためのアーキテクチャ戦略の概要について説明します。公式の GenAI SDK、Direct API（REST/gRPC）、OpenAI 互換レイヤを使用する場合の技術的なトレードオフについて詳しく説明します。

このガイドは、オープンソース フレームワーク、エンタープライズ ゲートウェイ、SaaS アグリゲータなどの他のデベロッパー向けのツールを構築しており、依存関係の衛生状態、バンドルサイズ、機能のパリティを最適化する必要がある場合に役立ちます。

パートナー統合とは

パートナーとは、Gemini API とエンドユーザー デベロッパー間の統合を構築するすべてのユーザーを指します。パートナーは 4 つのアーキタイプに分類されます。どのタイプに最も近いかを特定することで、適切な統合パスを選択できます。

エコシステム フレームワーク

• 対象者: オープンソース フレームワーク（LangChain、LlamaIndex、Spring AI など）または言語固有のクライアントのメンテナー。
• 目標: 幅広い互換性。ライブラリは、ユーザーが選択した環境で競合を強制することなく動作するようにします。

ランタイムとエッジ プラットフォーム

• 対象: コード実行が制限された環境で行われる SaaS プラットフォーム、AI ゲートウェイ、クラウド インフラストラクチャ プロバイダ（Vercel、Cloudflare、Zapier など）。
• 目標: パフォーマンス。低レイテンシ、最小バンドルサイズ、迅速なコールド スタートが必要である。

情報集約サイト

• 対象者: 多くの異なる LLM プロバイダ（OpenAI、Anthropic、Google など）へのアクセスを単一のインターフェースに正規化するプラットフォーム、プロキシ、または内部の「モデル ガーデン」。
• 目標: 移植性と均一性。

エンタープライズ ゲートウェイ

• 対象者: 大企業の内部プラットフォーム エンジニアリング チームで、数百人の内部開発者向けの「ゴールデンパス」を構築している方。
• 目標: 標準化、ガバナンス、統合認証。

主な相違点

グローバル 効果的な手法: 選択したパスに関係なく、すべてのパートナーは x-goog-api-client ヘッダーを送信する必要があります。

Google GenAI SDK の統合

フレームワークの場合、サポートされている言語のコード行数が最も少ないため、Google GenAI SDK を実装するのが最も簡単な方法です。

内部プラットフォーム チームの場合、主な成果物は、プロダクト エンジニアがセキュリティ ポリシーに準拠しながら迅速に作業を進めることができる「ゴールデン パス」であることがよくあります。

メリット:

• Gemini Enterprise Agent Platform 移行用の統合インターフェース: 内部デベロッパーは、API キー（Gemini API）を使用してプロトタイプを作成し、本番環境のコンプライアンスのために Gemini Enterprise Agent Platform（IAM）にデプロイすることがよくあります。SDK は、これらの認証の違いを抽象化します。フレームワークについても同様に、1 つのコードパスを実装して 2 つのユーザーセットをサポートできます。
• クライアントサイド ヘルパー: SDK には、複雑なタスクのボイラープレートを削減する慣用的なユーティリティが含まれています。
  • 例: プロンプト、自動関数呼び出し、包括的なタイプで PIL 画像オブジェクトを直接サポートします。
• リリース当日の機能アクセス: 新しい API 機能は、リリース時に SDK を通じて利用できます。
• コード生成のサポートの改善: ローカル SDK のインストールにより、型定義と docstring がコーディング アシスタント（Cursor、Copilot など）に公開されます。このコンテキストにより、生の REST リクエストを生成する場合と比較して、コード生成の精度が向上します。

トレードオフ:

• 依存関係の重みと複雑さ: SDK には独自の依存関係があり、バンドルサイズが増加し、サプライ チェーンのリスクが高まる可能性があります。
• バージョニング: 新しい API 機能は、多くの場合、最小 SDK バージョンに固定されます。新機能や新しいモデルを利用するには、ユーザーにアップデートをプッシュする必要がある場合があります。その場合、ユーザーに影響する推移的依存関係の変更が必要になることもあります。
• プロトコルの制限: SDK は、メイン API の HTTPS と Live API の WebSocket（WSS）のみをサポートします。高レベルの SDK クライアントを使用した gRPC は対象外です。
• 言語サポート: SDK は現在の言語バージョンをサポートしています。EOL バージョン（Python 3.9 など）をサポートする必要がある場合は、フォークを維持する必要があります。

おすすめの方法:

• バージョンをロックする: チーム間で安定性を確保するために、内部ベースイメージの SDK バージョンを固定します。

API との直接統合

ライブラリを数千人のデベロッパーに配布する場合、制約のある環境で実行する場合、Gemini の最先端の機能を必要とするアグリゲータを構築する場合は、REST または gRPC を使用して API と直接統合する必要があるかもしれません。

メリット:

• 機能アクセス: OpenAI 互換レイヤとは異なり、API を直接使用すると、File API へのアップロード、コンテンツ キャッシュの作成、双方向 Live API の使用など、Gemini 固有の機能を利用できます。
• 最小限の依存関係: サイズや監査費用が原因で依存関係が重要になる環境。fetch などの標準ライブラリや httpx などのラッパーを介して API を直接使用すると、ライブラリを軽量に保つことができます。
• 言語に依存しない: 言語制限がないため、Rust、PHP、Ruby など、SDK でカバーされていない言語では、このパスのみが使用されます。
• パフォーマンス: Direct API には初期化のオーバーヘッドがないため、サーバーレス関数のコールド スタートを最小限に抑えることができます。

トレードオフ:

• Gemini Enterprise Agent Platform の手動実装: SDK とは異なり、API を直接使用しても、AI Studio（API キー）と Gemini Enterprise Agent Platform（IAM）の認証の違いは自動的に処理されません。両方の環境をサポートする場合は、個別の認証ハンドラを実装する必要があります。
• ネイティブ型またはヘルパーがない: リクエスト オブジェクトのコード補完やコンパイル時チェックは、自分で実装しない限り取得できません。クライアントの「ヘルパー」（関数からスキーマへのコンバータなど）がないため、このロジックを手動で記述する必要があります。

ベスト プラクティス

Google は、ライブラリの型定義を生成するために使用できる機械可読仕様を公開しています。これにより、型定義を手動で記述する必要がなくなります。ビルドプロセス中に仕様をダウンロードし、型を生成して、コンパイルされたコードを配布します。

• エンドポイント: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK の統合

モデル固有の機能よりも統一されたスキーマ（OpenAI Chat Completions）を優先するプラットフォームの場合は、これが最も迅速な方法です。

メリット:

• 摩擦が少ない: baseURL と apiKey を変更するだけで、Gemini のサポートを追加できることがよくあります。これは、「Bring Your Own Key」の実装を統合し、新しいコードを記述せずに Gemini のサポートを追加する迅速な方法です。
• 制約: このパスは、OpenAI SDK に制限されており、File API などの高度な Gemini 機能や、Google 検索によるグラウンディングなどのツールのサポートを手動で追加する必要がない場合にのみ推奨されます。

トレードオフ:

• 機能の制限: 互換性レイヤは、Gemini のコア機能に制限を設けます。利用可能なサーバーサイド ツールはプラットフォームによって異なり、Gemini API ツールと連携するには手動での処理が必要になる場合があります。
• 変換のオーバーヘッド: OpenAI スキーマは Gemini のアーキテクチャに 1 対 1 でマッピングされないため、互換性レイヤに依存すると、ユーザーの「検索」ツールを適切なプラットフォーム ツールにマッピングするなど、解決するために追加の実装作業が必要となる複雑さが生じます。特別なケースが多数必要な場合は、プラットフォームごとに専用の SDK または API を使用する方が価値があるかもしれません。

ベスト プラクティス

可能な場合は、Gemini API と直接統合します。ただし、互換性を最大限に高めるには、さまざまなプロバイダを認識し、ツールとメッセージのマッピングを処理できるライブラリの使用を検討してください。

すべてのパートナー向けの 効果的な手法: クライアントの識別

プラットフォームまたはライブラリとして Gemini API を呼び出す場合は、x-goog-api-client ヘッダーを使用してクライアントを識別する必要があります。

これにより、Google は特定のトラフィック セグメントを特定できます。ライブラリで特定のエラー パターンが発生している場合は、デバッグのサポートについてご連絡いたします。

形式 company-product/version を使用します（例: acme-framework/1.2.0）。

実装の例

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

次のステップ

• ライブラリの概要で、Gen AI SDK について確認する
• API リファレンスを参照する
• OpenAI の互換性ガイドを読む