Gemini OpenAI SDK Google AI Chat Completions 互換 API

OpenAI SDK から互換エンドポイント経由で Gemini を使う

Google の OpenAI 互換 base URL またはマルチプロバイダーゲートウェイから、現行モデルエイリアスで Gemini を OpenAI Python/TypeScript SDK から呼び出します。

AveMujica API 2026年7月15日 2 分で読めます

公式 OpenAI SDK から Gemini を呼ぶには、base_url を Google の OpenAI 互換エンドポイント（または Gemini を前面に置く AI ゲートウェイ）に設定し、Gemini API キーまたはゲートウェイキーで認証し、通常の chat.completions リクエストで Gemini モデル ID を選びます。Google はこれを Gemini OpenAI 互換ガイドに記載しています。すでに OpenAI クライアント形に標準化しているチームは、全統合を書き直さずに Gemini を評価できます。

Google は、まだ OpenAI ライブラリを使っていない場合、全機能へアクセスする既定手段として Gemini API を直接呼ぶことも推奨しています。互換性は移行と評価の橋であり、OpenAI のすべての機能面が Gemini に存在するという主張ではありません。

なぜ OpenAI 互換が Gemini 採用で重要か

多くのコードベースはすでに openai パッケージ、LangChain/OpenAI チャットモデル、または /v1/chat/completions 向けの手書きクライアントに依存しています。毎回ネイティブ Gemini SDK を強制すると、認証ヘルパ・ストリーム解析・エラー処理が倍増します。互換により次が可能です。

一つのリクエストビルダとレスポンスパーサを維持
OpenAI 形トラフィック上で Gemini を A/B
資格情報をゲートウェイに移しつつクライアントを単純に保つ
初期評価で同じエージェントツールスキーマを再利用

互換性は依然として翻訳レイヤーです。Google は、一部の機能面について OpenAI ライブラリ対応を拡大中の beta と説明しています。設計レビューで機能パリティを約束する前に、現在の制限事項を読んでください。

最小クライアント設定

Google の OpenAI 互換エンドポイント直接

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "Answer with concrete engineering guidance."},
        {
            "role": "user",
            "content": "When should a team try Gemini through an OpenAI client?",
        },
    ],
)

print(response.choices[0].message.content)

TypeScript:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "system", content: "Answer with concrete engineering guidance." },
    {
      role: "user",
      content: "When should a team try Gemini through an OpenAI client?",
    },
  ],
});

console.log(response.choices[0]?.message?.content);

モデル ID は変わります。本番設定に古い Flash や Pro のスナップショット文字列をハードコードせず、Google のモデル一覧を優先してください。

マルチプロバイダ製品向けゲートウェイ経路

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="gemini-flash",  # stable alias mapped to gemini-3.5-flash (or successor)
    messages=[{"role": "user", "content": "Draft a checklist for model A/B tests."}],
)

上流の Gemini 資格情報をチャネルとして一度登録し、モデルカタログにエイリアスを公開し、アプリケーションの秘密はゲートウェイキーだけに限定します。これは OpenAI 互換 API ゲートウェイで説明する運用モデルと同じです。

安定エイリアスと生の上流 ID

アプリケーション設定は、運用者が制御するエイリアスに依存させます。

gemini-flash、gemini-pro、または製品固有の名前を公開します。
それらを現在の上流 ID（gemini-3.5-flash、Pro クラスの ID など）へマッピングします。
Google が後継モデルを出したら、マッピングだけを変更します。
マッピング変更後は短い回帰スイートを実行します。

これによりクライアントの PR はまれになり、ロールバックも設定変更で済みます。Flash と Pro の配置が明示的な製品判断であり続けるよう、エイリアス運用を遅延とコストのモデルルーティングと組み合わせてください。

チームが最初に試す機能

平文チャットとマルチターン

非ストリーミングチャットと固定評価セットから始めます。次を確認してください。

system 指示が守られる
マルチターンの文脈が保持される
max_tokens による切り詰めが製品の期待と一致する
拒否と空の応答を UI が処理できる

ストリーミング

大半のチャット製品は、すでに OpenAI SDK のストリームを扱っています。Gemini でストリーミングを有効にする場合は次を行います。

最初のトークンまでの時間を総所要時間とは別に測る
ストリームがエラーチャンクで終わった場合の UI 表示を決める
トークンを描画した後の無言フェイルオーバーを避ける

ストリーム初期と途中の失敗に関する信頼性ルールは、場当たり的なクライアント再試行ではなく LLM API フェイルオーバー戦略に置きます。

ツールと関数呼び出し

Gemini の OpenAI 互換インターフェースは、多くのエージェントワークフローでツールをサポートします。

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search internal engineering docs",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "limit": {"type": "integer"},
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "Find runbooks for gateway failover."}],
    tools=tools,
    tool_choice="auto",
)

副作用を起こす前に、ツール名を許可リストで確認し、引数を JSON Schema または Pydantic で検証してください。移植性の詳細と非互換マトリクスはプロバイダー横断のポータブルなツール呼び出しにあります。

Thinking / reasoning effort のマッピング

Gemini モデルは、OpenAI 互換フィールドを通じて推論設定を公開できます。モデルごとに reasoning effort の対応は異なるため、モデルがどれだけ深く考えるかを調整するときは Google の最新マッピング表を確認してください。モデル文字列しか設定できないクライアント向けに、ゲートウェイがモデルエイリアスの effort サフィックスを受け付ける場合もあります。それらは運用上の便宜として扱い、どのエイリアスがどの effort に対応するかを文書化してください。

Embeddings と隣接エンドポイント

Embeddings やメディアワークフローでは、別々のエンドポイント確認が必要になることがよくあります。Google の OpenAI 互換ページはチャット中心の例を先に扱っており、一部のバッチ処理におけるファイルの upload/download 互換は、まだネイティブ Google クライアントを必要とする場合があります。「OpenAI SDK 全体が動く」と宣言する前に、隣接する各機能を個別の curl で確認してください。

予算に織り込むべき制限と不一致

製品について、曖昧な「すべてテストする」という注意ではなく、明示的な不一致リストを作ってください。

未対応または黙って破棄される OpenAI パラメーター
マルチモーダル部分のエンコード差異、特に画像と音声
ツール呼び出しの境界事例（並列呼び出し、空の引数オブジェクト、enum のずれ）
OpenAI とは異なる拒否形式を返す安全フィルター
Google が現在の制限事項に記載している beta の不足
rate limit とエラーヘッダーの差異

OpenAI では成功したリクエストが Gemini で 400 を返す場合、OpenAI 専用フィールドを1つずつ外し、生のエラー本文を記録してください。すべての例外を捕まえてストリーム途中に別プロバイダーへ再試行することで「修正」してはいけません。

偽の自信を避ける評価計画

期待するツール名を必要に応じて含む 20〜50 件のプロンプトスイートを固定します。
現在の既定モデルと gemini-3.5-flash（または Pro エイリアス）で実行します。
スキーマ妥当性と必須ツールの呼び出しを、文章品質とは別に採点します。
p50/p95 遅延と成功タスク当たりコストを測定します。
その後にだけルーティング方針を変更します。Gemini が遅延では勝つ一方、スキーマ妥当性で負けるなら、自由度の高い文章を許容できるワークフローだけを割り当ててください。

アプリケーションコードより先に行う curl 確認

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-flash",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ]
  }'

Google をノート PC から直接試す場合は、ホストを https://generativelanguage.googleapis.com/v1beta/openai/ に替え、Gemini API キーを使います。共有環境では資格情報を各ワークステーションへコピーしないよう、ゲートウェイ経路を優先してください。

Gemini をチャネルとして運用する

マルチプロバイダー環境では、Gemini を他のチャネルと同じように扱います。

資格情報をサーバー側に保存する
Google が ID を改名または廃止したときにモデルエイリアスを見直す
rate limit と予算をチームまたは製品ごとに分ける
健全性とエラー率を他プロバイダーと並べて表示する
既定ルーティングを変えるときに料金コンテキストを確認する

これがマルチプロバイダー LLM ゲートウェイを運用可能に保つ方法です。Gemini はルーティング先であり、第2のアプリケーションアーキテクチャではありません。

セキュリティとキー衛生

ブラウザやモバイルアプリに Gemini キーを埋め込まない。
サービスごとに最小権限のゲートウェイスコープキーを使う。
ツール引数のログは慎重に。
エージェントが外部ツールを自動呼び出しできる場合は OWASP LLM 指針を確認する。過度な自律性はモデルだけでなく製品のリスクです。

移行手順

Gemini チャネルを有効化し curl で /v1/chat/completions を確認。
非クリティカルなサービスを Gemini 別名に向ける。
評価スイートでスキーマ/ツール成功率を比較。
ストリーミングクライアントを追加。
サーバ側引数検証付きツールエージェントを追加。
ルーティングで pin / canary / failover を決める。
トラフィック拡大前にロールバック別名を文書化。

公式情報源

最終確認：2026-07-15。本番ルーティングを固定する前に、Google のドキュメントでモデル ID、エンドポイントパス、制限事項の表を確認してください。

よくある質問

Gemini の OpenAI 互換エンドポイントは完全な OpenAI クローンですか？

いいえ。一般的な OpenAI クライアントワークフロー向けの互換レイヤーです。一部のエンドポイント、パラメーター、挙動は異なります。依存する機能について Google の制限事項を読んでください。まだ OpenAI ライブラリへ投資していない場合、Google は引き続きネイティブ Gemini API を推奨しています。

Google の base URL とゲートウェイのどちらで Gemini を使うべきですか？

Google の base URL は迅速なローカル実験に使います。複数サービス、チーム、プロバイダー、予算、監査要件が関わる場合はゲートウェイを使います。

どの Gemini モデルから始めるべきですか？

遅延重視の評価では、Google のドキュメントにある現行 Flash クラスの ID（執筆時点のサンプルは gemini-3.5-flash）から始め、難しい推論やツールワークフローには Pro クラスを使います。生の ID をアプリ設定へ散らさず、安定したゲートウェイエイリアスへマッピングしてください。

OpenAI と同じツールスキーマを保てますか？

初期移植では多くの場合そのまま使えますが、各スキーマを検証してください。並列ツール呼び出し、strict JSON、境界的な引数エンコードは Gemini 上で明示的なテストが必要です。

最初の Gemini カナリア

Gemini チャネルを作成または選択し、ゲートウェイに対して OpenAI SDK から /v1/chat/completions を呼び、少なくとも1回のツール呼び出しを含む固定20プロンプト評価を実行します。スキーマ成功率と遅延を現在の既定モデルと比較し、その後で Gemini をそのワークフローの既定、canary、failover のどれにするか決めてください。