OpenAI 互換 API ガイド:Base URL だけ変えて移行

OpenAI 互換で共通化される範囲、既存のクライアントを Modelflare に移行する方法、本番トラフィックを流す前に確認すべき境界を解説します。

OpenAI 互換 API ガイド:Base URL だけ変えて移行

OpenAI 互換 API を使うと、既存のクライアントで使い慣れた認証ヘッダー、JSON のリクエスト形式、ストリーミングの仕組みをそのまま保ちながら、トラフィックを別のゲートウェイに送れます。変更は Base URL と API キーの差し替えだけで済むこともありますが、互換性はあくまでプロトコル上の仕様です。すべてのモデルがすべてのエンドポイントやプロバイダー固有のフィールドに対応することを約束するものではありません。

このガイドでは、OpenAI 形式の API をすでに利用しているアプリケーション、スクリプト、AI ツールを安全に移行する手順を説明します。

OpenAI 互換で実際に共通化される範囲

仕様のうち、そのまま再利用しやすいのは次の部分です。

  • Authorization ヘッダーによる Bearer トークン認証。
  • バージョン付きの /v1 エンドポイントでやり取りする JSON のリクエストとレスポンス。
  • /v1/models、/v1/chat/completions、/v1/responses などの一般的なエンドポイント。
  • ストリーミングに対応したリクエストでの Server-Sent Events。
  • 選択したプロトコルが対応している場合の、model、messages、input、stream などのおなじみのリクエストフィールドとツール定義。

互換性があるからといって、1 つのモデルを Chat Completions と Responses の間で自由に移せるわけではありません。モデルによっては、検証済みの 1 つのプロトコルでしか提供されないことがあります。また、プロバイダー固有の推論、検索、マルチモーダルのフィールドには、ゲートウェイ側での変換ではなく、無変換のパススルーが必要になる場合もあります。

利用するモデル、グループ、API 形式については、最新のモデルと料金カタログを正式な情報源として確認してください。

移行の準備

アプリケーションのコードを変更する前に、次の準備をします。

  1. 個人用のキーや無関係な連携用のキーを使い回さず、API キーで専用のキーを作成します。
  2. 対象のモデルにアクセスできるプライマリのモデルグループを選択します。
  3. フォールバックグループは、同じモデルに対応し、かつ同じコストと信頼性の方針に合う場合にのみ、順序を付けて追加します。
  4. 移行前後の動作を比較できるように、現在のエンドポイント、モデル ID、ストリーミング設定、ツールの利用状況を記録しておきます。

Modelflare の OpenAI 互換の正式な Base URL は次のとおりです。

https://modelflare.dev/v1

多くの SDK は、Base URL が /v1 で終わることを前提に、/chat/completions や /responses を自動で付け加えます。エンドポイントのパスを二重に付けてしまわないよう、事前にクライアントのドキュメントを確認してください。

まず認証とモデルへのアクセスを確認する

API キーはソースコードに書かず、環境変数に保存します。

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

次に、そのキーで利用可能なモデルの一覧を取得できることを確認します。

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

成功すれば、ホスト名、TLS の経路、API キーが有効であることを確認できます。ただし、返されたすべてのモデルで特定のリクエスト形式が使えることまでは確認できないため、次は実際に使うエンドポイントで確認します。

実際に使うプロトコルでリクエストを 1 件送信する

Chat Completions 形式に対応していると掲載されているモデルの場合:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with the active model name."}
    ],
    "stream": false
  }'

Responses 互換のコーディングモデルの場合:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Reply with the active model name.",
    "stream": false
  }'

モデル ID は、最新のカタログに表示されているとおりに正確に指定してください。model_not_found が返された場合、通常は選択したキーまたはグループがそのモデルにアクセスできないことを意味します。大文字と小文字を変えれば解決するという意味ではありません。

ストリーミングは別途検証する

ストリーミングに依存するアプリケーションでは、非ストリーミングのリクエストが成功しただけでは不十分です。"stream": true を指定して同じリクエストを送り、イベントが段階的に届くこと、そしてクライアントがレスポンス全体をバッファしてから描画していないことを確認してください。

ストリームが遅い原因を調べるときは、次の時間を分けて考えます。

  • 認証とルートの選択にかかった時間
  • サービス提供元のレスポンスヘッダーが返るまでの時間
  • 最初の有効なコンテンツまたはツールの差分が届くまでの時間
  • 可視出力が始まった後の生成スループット

Modelflare の利用ログには、この目的のためにリクエスト単位のタイミングメタデータが保持されます。プロンプト、レスポンスのテキスト、生のリクエストボディ、API キー、メールアドレス、平文の IP アドレスは保存されません。

本番移行のチェックリスト

  • API キーをシークレットストアまたは環境変数に保管する
  • Base URL を https://modelflare.dev/v1 に固定する
  • 選択したエンドポイントに明示的に対応しているモデルを使う
  • 非ストリーミングとストリーミングをそれぞれ個別にテストする
  • アプリケーションで使用している場合は、ツール、構造化出力、推論の制御、マルチモーダル入力もテストする
  • クライアントのリクエストで意味を持つ場合は、ゼロや false の明示的な値を省略せずに保持する
  • クライアントのタイムアウトは、短いヘルスチェック用のプロンプトではなく、実際のワークロードに合わせて設定する
  • 切り替え後は、利用ログでステータス、レイテンシ、トークン使用量、選択されたグループ、コストを確認する

プロトコルの境界を確認できれば、クライアントは通常、既存のリクエストのライフサイクルをそのまま維持できます。そのうえで、互換エンドポイントの背後では、Modelflare がモデルへのアクセス、ルーティングの方針、リクエスト単位の可視性を提供します。

このエンドポイントの背後にある運用レイヤーについては、AI API ゲートウェイとは?をお読みください。クライアントで複数の OpenAI 形式を使える場合は、パスを変更する前に Responses API と Chat Completions の比較を確認してください。