2026-07-28

OpenAI互換APIガイド：Base URLの変更方法

OpenAI互換APIが共通化する範囲、既存クライアントをModelflareへ切り替える方法、本番利用前に確認すべき境界を解説します。

OpenAI互換APIを使うと、既存クライアントの認証ヘッダー、JSONリクエスト形式、ストリーミング方式を保ちながら、トラフィックを別のゲートウェイへ切り替えられます。変更がBase URLとAPIキーの差し替えだけで済む場合もありますが、互換性はあくまでプロトコル契約です。すべてのモデルがすべてのエンドポイントやプロバイダー固有フィールドをサポートするという意味ではありません。

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

OpenAI互換で共通化できる範囲

再利用しやすい契約は次のとおりです。

AuthorizationヘッダーによるBearer Token認証
バージョン付き/v1エンドポイント上のJSONリクエストとレスポンス
/v1/models、/v1/chat/completions、/v1/responsesなどの一般的なエンドポイント
対応するストリーミングリクエストでのServer-Sent Events
プロトコルが対応するmodel、messages、input、stream、ツール定義

互換性があっても、同じモデルをChat CompletionsとResponsesの間で自由に移動できるとは限りません。モデルが検証済みの一方のプロトコルだけで公開される場合があります。プロバイダー固有の推論、検索、マルチモーダル設定では、ゲートウェイ変換ではなくRaw Pass-throughが必要になることもあります。

利用するモデル、グループ、API形式は、最新のモデルと料金で確認してください。

移行前の準備

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

個人用や別の連携用キーを流用せず、API Keysで専用キーを作成する
対象モデルへアクセスできるプライマリグループを選ぶ
同じモデルをサポートし、コストと信頼性の方針に合うグループだけを順序付きフォールバックへ追加する
現在のエンドポイント、モデル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": "現在のモデル名を回答してください。"}
    ],
    "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": "現在のモデル名を回答してください。",
    "stream": false
  }'

モデルIDは最新カタログの表記をそのまま使用します。model_not_foundの場合は、大文字・小文字だけでなく、キーとグループがそのモデルへアクセスできるか確認してください。

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

非ストリーミングが成功しても、ストリーミング依存アプリの動作確認にはなりません。"stream": trueでイベントが段階的に届くか、クライアントが全レスポンスをバッファしていないかを確認します。

遅いストリームを調べる際は、次を分けて確認します。

認証とルート選択までの時間
アップストリームのレスポンスヘッダーまでの時間
最初の有効なテキストまたはツールイベントまでの時間
可視出力開始後の生成速度

Modelflareの使用量ログにはリクエスト単位のタイミング情報が残りますが、プロンプト、レスポンス本文、Raw Request Body、APIキー、メールアドレス、平文IPアドレスは保存されません。

本番移行チェックリスト

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

プロトコル境界を確認できれば、クライアントの既存リクエストライフサイクルを保ちながら、互換エンドポイントの背後でModelflareのモデルアクセス、ルーティング、リクエスト単位の可視性を利用できます。