OpenAI互換のモデル名は、それ以外がきれいに移行できている場合でも、ひっそりと破綻が起きる場所です。SDKはmodel文字列を受け入れ、リクエスト形式も見慣れたもので、ベースURLはOpenAI互換のルートを指しています。ところが本番ではmodel_not_found、誤った機能への静かなフォールバック、あるいは画像モデルをチャットエンドポイントに送ってしまう事態が起こります。
解決策は、あらゆるプロバイダーのカタログを暗記することではありません。OpenAI互換のモデル名は、管理された設定として扱ってください。各文字列は、プロバイダーのカタログ、エンドポイントファミリー、ルート、バージョンポリシー、課金記録に紐づきます。実際のトラフィックを移す前に、この5つすべてを確認してください。
Flatkeyは、この点で役立ちます。チームは1つのゲートウェイの背後で、モデルアクセス、ルーティング、課金、利用分析、運用レビューを集約できます。しかし、ゲートウェイがあっても、曖昧なモデル文字列が安全になるわけではありません。このガイドでは、ベースURL、SDK設定、または本番エイリアスを変更する前に、OpenAI互換のモデル名を検証するためのワークフローを示します。
OpenAI互換のモデル名がずれていく理由
「OpenAI互換」はAPIの形を指す言葉であり、普遍的な命名標準を意味するわけではありません。互換エンドポイントはOpenAI形式のJSONやSDKを受け入れつつ、独自のモデルIDを要求する場合があります。
つまり、次の文字列は互換ではありません:
| 文字列の出どころ | 失敗しうる理由 |
|---|---|
| プロバイダーのマーケティングページ | 表示されている製品名がAPIのモデルIDではない可能性があります。 |
| 古いコードサンプル | モデルが非推奨、改名済み、または別のエンドポイントに限定されている場合があります。 |
| 別のゲートウェイ | ゲートウェイのエイリアスはローカルなルーティング設定であり、プロバイダー全体の真実ではありません。 |
| 別のエンドポイントファミリー | Chat、Responses、embeddings、画像、音声、動画の各ルートで、公開されるモデルセットが異なることがあります。 |
| 別のリージョンまたはワークスペース | プロバイダーによっては、エンドポイントとモデルカタログがリージョン、ワークスペース、またはアカウント権限に依存します。 |
安全なルールはシンプルです。OpenAI互換のモデル名を記憶だけで承認しないでください。現在のカタログ、現在のエンドポイントファミリー、そしてスモークテストで承認してください。
モデル名検証ワークフロー
OPENAI_BASE_URL、baseURL、model、Flatkeyのエイリアス、または本番のルーティングポリシーを変更する前に、このワークフローを使ってください。
| ステップ | 確認事項 | 保存する証跡 |
|---|---|---|
| 1. カタログ | 現在のプロバイダーまたはFlatkeyのカタログに、この完全一致のモデル文字列は掲載されていますか? | タイムスタンプ付きのスクリーンショット、APIの読み戻し、またはカタログのエクスポート。 |
| 2. エンドポイントファミリー | そのモデルはchat/completions、responses、画像、embeddings、または別のルートで有効になっていますか? |
ルート固有のドキュメントと、最小限の1件のリクエスト。 |
| 3. エイリアスの所有者 | アプリはプロバイダー直指定のIDを使っていますか、それともゲートウェイのエイリアスを使っていますか? | 設定ファイル、Flatkeyのモデルエイリアス、所有者/チーム欄。 |
| 4. バージョンポリシー | その文字列は安定版、日付付き、プレビュー、非推奨、またはプロバイダー経由ルーティングですか? | 非推奨 नोट、モデルページ、変更履歴、または承認記録。 |
| 5. 実行時の証明 | そのアプリ環境から、完全一致のルートを成功裏に呼び出せますか? | Curlのレスポンス、SDKのレスポンス、リクエストID、利用記録。 |
| 6. ロールバック | 失敗した場合、どの文字列とルートに戻しますか? | 前回の設定、機能フラグ、ロールバック担当者。 |
これがモデル名チェックリストの核心的な価値です。OpenAI互換のモデル名を、場当たり的な文字列からレビュー済みのデプロイ入力へと変えます。
学ぶべき現在のプロバイダー例
まず公式ドキュメントでパターンを理解し、そのうえで本番投入前に自分のアカウントやゲートウェイのカタログを確認してください。
| プロバイダーパス | 2026年7月7日時点で確認した公式パターン | 移行時の教訓 |
|---|---|---|
| OpenAI | APIはChat CompletionsとResponsesでmodelフィールドを使用し、List modelsエンドポイントは認証済みアカウントで利用可能なモデルを返します。現在のOpenAIのモデルガイダンスではgpt-5.5が最新ファミリーとして示されていますが、API例では古い例示文字列が引き続き表示されることがあります。 |
契約はドキュメントで確認し、利用可否はアカウントのカタログで確認してください。 |
| Google Gemini OpenAI compatibility | Googleはhttps://generativelanguage.googleapis.com/v1beta/openai/配下のOpenAI互換ベースURLと、チャット用のgemini-3.5-flashなどの例を文書化しています。 |
GeminiモデルをOpenAI風の名前に置き換えないでください。GeminiのIDを維持してください。 |
| xAI | xAIのドキュメントでは、base_url="https://api.x.ai/v1"を使うOpenAI SDKの利用法と、grok-build-0.1のようなモデル文字列の例が示されています。 |
SDKの形はOpenAI風でも、モデル文字列はxAI固有のままです。 |
| Alibaba Cloud DashScope | DashScopeは、Qwenモデル向けのOpenAI互換モード、リージョンまたはワークスペース固有のcompatible-mode/v1 URL、そしてqwen-plusのような例を文書化しています。 |
ベースURL、リージョン、ワークスペース、モデル名はひとまとまりです。まとめて確認してください。 |
| Flatkey | Flatkeyの公開ホームページでは、https://router.flatkey.ai/v1/chat/completionsにOpenAI風のルートが示されており、1つのキー、モデルアクセス、ルーティング、課金、利用分析、運用制御を中心に製品が位置づけられています。 |
実際のエイリアスは現在のFlatkeyコンソールまたはカタログで確認し、そのうえで完全一致のルートをスモークテストしてください。 |
これらの例は、OpenAI互換のモデル名をプロバイダー固有の文字列として扱うべき理由を示しています。互換性はクライアント側の変更を減らしますが、カタログ上の違いを消すわけではありません。
承認済みモデルマップを作成する
生のモデル文字列をアプリコード、ノートブック、自動化ツール、サポートスクリプトに散在させないでください。承認済みのOpenAI互換モデル名を小さな1つのマップにまとめ、すべてのサービスをそこ経由でルーティングしてください。
type EndpointFamily = "chat" | "responses" | "embeddings" | "images" | "video";
type ApprovedModelRoute = {
alias: string;
providerModel: string;
endpointFamily: EndpointFamily;
baseURL: string;
owner: string;
reviewedAt: string;
rollbackAlias: string;
};
export const models: Record<string, ApprovedModelRoute> = {
support_chat: {
alias: "support_chat",
providerModel: process.env.FLATKEY_SUPPORT_CHAT_MODEL!,
endpointFamily: "chat",
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
owner: "support-platform",
reviewedAt: "2026-07-07",
rollbackAlias: "support_chat_previous",
},
};
このマップは、アプリが使う名前と、プロバイダーまたはゲートウェイのモデル文字列を分離します。これにより、調達、財務、インシデント対応者が「誰がこのモデルを承認したのか」「どのエンドポイント向けなのか」「どうロールバックするのか」を確認できる、安定した参照先ができます。
より広いカタログ統治については、AIモデルカタログガイドも併せてご覧ください。base URL の移行については、OpenAI互換API移行ガイドを使用してください。
SDK移行前に正確な名前をスモークテストする
モデル名のスモークテストは、手で確認できる程度に小さくするべきです。ツール、ストリーミング、JSONスキーマ、フレームワークラッパーから始めないでください。出荷予定のルート、キー、モデル文字列から始めてください。
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="the-current-flatkey-model-alias"
curl -sS "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with exactly: model route ok"}
]
}'
これが失敗した場合、SDKをデバッグしないでください。まずモデル文字列、エンドポイントファミリー、キーのスコープ、ルート、カタログを確認してください。成功したら、レスポンス本文、ステータスコード、あればリクエストID、タイムスタンプ、usageオブジェクト、そしてFlatkeyのusage readbackを保存してください。
次に、同じOpenAI互換モデル名をSDK経由でもテストします:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL!,
messages: [{ role: "user", content: "Reply with exactly: sdk route ok" }],
});
console.log(response.choices[0]?.message?.content);
SDKテストでは、同じbase URLルート、同じモデルエイリアス、同じエンドポイントファミリーを使うべきです。curlは成功するのにSDKが失敗する場合は、モデル名を変更する前に環境変数を確認してください。
エイリアスをプロバイダーIDと分離する
エイリアスはプロバイダーIDと同じものではありません。プロバイダーIDは、上流のプロバイダーまたはプロバイダー互換ルートが受け付ける文字列です。ゲートウェイのエイリアスは、ゲートウェイがプロバイダーモデル、フォールバックポリシー、価格帯、またはアカウントにマッピングする文字列です。
どちらも有効であり得ます。問題は、チームがどちらを使っているのかを明示しなくなったときに始まります。
次の命名規律を使ってください:
| Field | Example Shape | Rule |
|---|---|---|
| App alias | support_chat |
アプリケーションが使う安定した名前。 |
| Gateway alias | support-chat-balanced |
ゲートウェイまたはプラットフォームチームが管理。 |
| Provider model ID | qwen-plus, gemini-3.5-flash, or current catalog value |
プロバイダーのドキュメントまたはカタログで確認済み。 |
| Endpoint family | chat, responses, images, embeddings |
ルートとパーサーに一致している必要があります。 |
| Version state | stable, preview, dated, deprecated | 本番トラフィックの前に確認済み。 |
これにより、OpenAI互換モデル名を監査可能にできます。ルートが失敗した場合、問題がアプリのエイリアスなのか、Flatkeyのエイリアスなのか、プロバイダーのモデルIDなのか、エンドポイントファミリーなのかを切り分けられます。
エンドポイントファミリーの不一致を避ける
model_not_found は、必ずしも文字列のスペルミスを意味しません。別のルートでは有効な文字列である可能性もあります。
チャットモデルはResponsesルートでは利用できないかもしれません。画像モデルは画像生成エンドポイントを使う場合があります。動画モデルは別のペイロードファミリーを必要とすることがあります。プロバイダー互換レイヤーは、サポートされていないフィールドを黙って無視したり、プロバイダーのカタログの一部しか公開しなかったりすることがあります。
オプションパラメータを追加する前に、次の質問に答えてください:
- このモデルは、呼び出しているルートで承認されていますか？
- このエンドポイントは
messages、input、prompt、画像、ファイル、または別のリクエスト形式を想定していますか？ - 選択した SDK は、ベース URL の後ろにエンドポイントパスを付加しますか？
- プロバイダーは、リージョン固有またはワークスペース固有のベース URL を必要としますか？
- Flatkey は、このエイリアスをステージングと本番で同じエンドポイントファミリーにルーティングしますか？
OpenAI互換 API のトラブルシューティングガイドでは、より広範なデバッグ手順を扱っています。モデル名の作業では、失敗の範囲を小さく保ってください。1つのルート、1つのモデル文字列、1つの短いリクエストです。
バージョン変更と非推奨化の変更に備える
OpenAI互換のモデル名は時間とともに変化します。安定したファミリー名もあれば、日付付きのスナップショットもあり、プレビュー版もあり、そして自社チームが管理するゲートウェイのエイリアスもあります。
本番の各モデルルートについて、見直しの周期を設定してください。
| シグナル | 対応 |
|---|---|
| 新しいプロバイダーモデルファミリー | まずはステージングのみに追加し、その後、品質、コスト、レイテンシ、ツールの挙動を比較します。 |
| プレビューまたはベータのサフィックス | 本番利用の前に、担当者とロールバック日を必須にします。 |
| 非推奨通知 | 期限、代替、テスト計画、ルート責任者を含む移行タスクを作成します。 |
| ゲートウェイのエイリアス変更 | 本番設定を更新する前に、スモークテストと利用状況の読み戻しを実施します。 |
| プロバイダーのリージョン変更 | ベース URL、ワークスペース、カタログ、課金、レイテンシを再確認します。 |
これらの判断を環境変数だけに埋もれさせないでください。エンジニアリング、運用、調達の各部門が、なぜそのモデルが許可されているのか確認できるよう、証跡をレビュー可能なパッケージとして残してください。
切り替え前に Flatkey で確認すべきこと
Flatkey は、検証を省略する理由ではなく、運用上の管理ポイントとして使ってください。
本番トラフィックを移行する前に、次を確認してください。
- コンソールまたはオンボーディングノートにある現在の Flatkey ベース URL。
- アプリから送信する正確なモデルエイリアス。
- そのエイリアスの背後にあるプロバイダーモデルまたはルート。
- Chat Completions や Responses などのエンドポイントファミリー。
- キーまたはワークスペースのクォータと利用上限。
- スモークテスト成功後の利用状況の読み戻し。
- 主要ルートが失敗した場合のフォールバック挙動。
- 以前のプロバイダールートまたは以前の Flatkey エイリアスに戻すためのロールバック設定。
そのうえで、Flatkey の料金と、テスト用のパスとしてのキーの取得に関する運用面を比較してください。料金ページやモデルカタログのページは、移行当日に確認した場合にのみ最新の証拠として扱ってください。
よくある質問
OpenAI互換のモデル名は共通ですか？
いいえ。OpenAI互換のモデル名も、依然としてプロバイダー固有またはゲートウェイ固有の文字列です。リクエスト形式は互換でも、モデルカタログは異なる場合があります。
なぜ OpenAI互換のルートは model_not_found を返すのですか？
モデル文字列のスペルミス、アカウントで利用不可、ゲートウェイで無効化、誤ったエンドポイントファミリーへの送信、別リージョンへのスコープ設定、または非推奨化が原因かもしれません。現在のカタログで正確な文字列を確認し、最小構成のルートテストを実行してください。
プロバイダーの直接のモデル ID と Flatkey のエイリアス、どちらを使うべきですか？
集中ルーティング、課金、利用状況の確認、フォールバック制御、またはチームレベルのガバナンスが必要なら、Flatkey のエイリアスを使ってください。エイリアスは検証済みのプロバイダーモデル ID に紐づけ、責任者を文書化しておきます。
古いプロバイダーのガイドからモデル名をコピーしてもよいですか？
出発点としてなら可能です。古いガイドには、廃止済み、プレビュー、または例示専用の文字列が含まれていることがあります。現在のプロバイダードキュメント、現在の Flatkey カタログ、そして1回の実際のスモークテストを再確認してください。
モデル名変更のレビューには何を含めるべきですか？
旧文字列、新文字列、エンドポイントファミリー、ベース URL、プロバイダーまたは Flatkey のエイリアス、責任者、参照元ドキュメント、スモークテストの応答、利用状況の読み戻し、予想コストへの影響、フォールバック挙動、ロールバック計画を含めてください。
要点
OpenAI互換のモデル名は、些末な情報ではなく移行の入力です。本番トラフィックを変更する前に、カタログ、エンドポイントファミリー、エイリアスの責任者、バージョンポリシー、実行時の証拠を確認してください。それらの確認を Flatkey に集約すれば、同じモデル名の証跡が、エンジニアリングの切り替え、インシデントレビュー、利用状況の照合、調達承認を支えることができます。
テストの準備ができたら、1つのキー、1つのベース URL、1つのエンドポイントファミリー、そして1つの承認済みモデルエイリアスから始めてください。それが、OpenAI互換のモデル名を本番運用に十分“地味”なものにする最短の方法です。
