お使いのアプリがすでに OpenAI compatible API を利用しているなら、Flatkey への移行をリライトから始めるべきではありません。管理された移行手順はもっと小さく済みます。Flatkey のキーを取得し、OpenAI compatible の SDK の接続先を https://router.flatkey.ai/v1 に向け、Flatkey カタログからモデル ID を選び、実際のトラフィックを送る前に、最初のリクエストをログ、クォータ、請求で確認します。
それが OpenAI compatible API の実用的な価値です。一般的なリクエストについては同じメンタルモデルを維持しつつ、プロバイダーへのアクセスを単一のゲートウェイの背後にまとめられます。Flatkey の公開製品コピーはこの動きに沿って構成されています。1 つの API キー、1 つのベース URL、明確な価格設定、統合請求、そしてキー、使用量、ルーティングを確認できる 1 つのダッシュボードです。
このガイドでは移行のランブックを示します。ベース URL の変更、SDK の例、モデル ID のマッピング、スモークテスト、エンドポイントの確認、使用ログのレビュー、クォータ設定、請求の検証、ロールバックを扱います。既存の Chat Completions スタイルのワークフローを Flatkey に移すときや、1 つの OpenAI compatible API エンドポイントの背後で複数モデルのスタックを標準化するときに使ってください。
OpenAI互換API移行で何が変わるのか？クイック回答
既存のOpenAI互換チャットクライアントの多くでは、最初の移行はアプリケーションの再実装ではなく、設定変更です。
| 設定 | 移行前 | Flatkey利用時 |
|---|---|---|
| APIキー | プロバイダー固有のOpenAI、Gemini、DeepSeek、またはプロキシキー | Flatkey APIキー |
| Base URL | プロバイダーのデフォルトまたは別のOpenAI互換Base URL | https://router.flatkey.ai/v1 |
| チャットエンドポイント | /v1/chat/completions |
Flatkey経由の/v1/chat/completions |
| モデル | 既存のプロバイダーモデルID | 料金/ダッシュボードから選択したFlatkeyモデルID |
| 検証 | 成功レスポンスのみ | レスポンス + 使用量ログ + コスト + クォータ + ロールバック |
重要なのは「互換性」です。OpenAI互換APIは、すべてのプロバイダー、モデル、エンドポイント、パラメータがOpenAIとまったく同じように動作することを保証するものではありません。Base URL、キー、モデルが正しい場合に、一般的なクライアント呼び出しが機能するよう、OpenAIのリクエスト/レスポンスパターンに十分従っていることを意味します。移行チェックリストでは、アプリが使用する正確な機能を検証する必要があります。
OpenAI互換エンドポイントが移行レイヤーになりつつある理由
OpenAI compatible API の検索結果は、主に公式リファレンス、プロバイダードキュメント、プラグイン、ローカルサーバーのドキュメント、そしてコミュニティの質問です。それは理にかなっています。開発者は単に「互換性とは何か？」と尋ねているのではありません。すべての呼び出し箇所を変更せずに、モデルプロバイダー間でコードを移行しようとしているのです。
Google の Gemini ドキュメントには、Gemini の OpenAI 互換ベース URL を設定して chat completions を呼び出す OpenAI ライブラリの例が示されています。DeepSeek の公式 API ドキュメントには、DeepSeek のベース URL と deepseek-chat や deepseek-reasoner のようなモデル ID を使う OpenAI SDK の例が示されています。パターンは明確です。多くのプロバイダーは、開発者がすでに使っている既存の SDK の場所で開発者に応えているのです。
Flatkey は、別の目的のために同じ移行の考え方を使っています。1 つのプロバイダーの OpenAI compatible API を 1 つのプロバイダーアカウントに向けるのではなく、Flatkey はチームに対して、マルチモデルアクセス、統合請求、ダッシュボードでの可視性を備えた 1 つの OpenAI 互換ベース URL を提供します。
ステップ 1: すでに持っているクライアントを棚卸しする
ベースURLを変更する前に、現在のアプリが実際に何を使っているかを書き出してください。クリーンな OpenAI compatible API の移行は、新しいサンプルアプリではなく、実際のライブ呼び出しの形から始まります。
| 確認項目 | 記録する内容 |
|---|---|
| SDK | Python、Node、直接HTTP、LangChain、LiteLLM、Vercel AI SDK、または別のラッパー。 |
| Endpoint | Chat Completions、Responses、embeddings、images、video、またはプロバイダ固有のエンドポイント。 |
| Model ID | 本番で使用している正確な文字列と、フォールバックモデル。 |
| Message shape | System prompts、developer messages、tool messages、multimodal content、またはプレーンテキストのみ。 |
| Parameters | Streaming、temperature、max tokens、tool calls、JSON output、response format、seed、timeout、retries。 |
| Observability | 現在、レイテンシ、トークン使用量、リクエストID、エラー、コストをどこで確認しているか。 |
| Rollback | 旧APIキー/base URL/modelをどれだけ早く復元できるか。 |
この棚卸しによって、移行を実態に即したものにできます。アプリが単純なチャットメッセージしか送らないなら、最初のFlatkeyテストは小さく保てます。ストリーミング、tool calls、JSON mode、images、video、または Responses API に依存している場合は、各機能を個別のスモークテストとして扱ってください。
ステップ 2: ベースURLを1つの設定レイヤーの背後に置く
新しい OpenAI 互換のベースURLをコードベース全体に散らさないでください。1つの環境変数、または1つの SDK ファクトリにまとめてください。
推奨される環境変数:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"OPENAI_BASE_URL を使うのは、多くの SDK ラッパーがすでにその規約をサポートしているため、便利なことが多いです。FLATKEY_API_KEY と FLATKEY_MODEL を使うと、新しい認証情報とモデルの選択を明示的に保てます。
ここで Flatkey は openai compatible base url の検索意図に合致します。移行は1つの差分でレビュー可能であるべきです。つまり、ベースURL、キー、モデル、検証手順です。
ステップ 3: Curl によるスモークテストを実行する
アプリケーションを変更する前に、まずは直接 HTTP リクエストを送ってください。これにより、キー、ベース URL、エンドポイント、モデル ID の問題を切り分けられます。
テンプレートのみ: レビュアーは、有効な Flatkey キーと確認済みの公開日モデル ID を使用して実行してください。
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "この Flatkey スモークテストが成功したことを 1 文で返答してください。"
}
]
}'有用なスモークテストは、200 OK 以上のことを証明します。OpenAI 互換 API への移行では、次を確認してください:
- レスポンスに使用可能なアシスタントメッセージが含まれている。
- モデル名がテスト対象として意図したものである。
- 利用状況が Flatkey ダッシュボードまたは使用ログに表示される。
- トークン数とコストが、請求確認に十分な形で表示される。
- モデル ID やキーが誤っている場合、エラーメッセージが理解しやすい。
- 古いベース URL とモデルを迅速に復元できる。
ステップ 4: Python OpenAI SDK の設定を変更する
Python アプリがすでに OpenAI SDK を使用している場合は、クライアントの生成を中央集約したままにしてください。
テンプレートのみ: レビュー担当者は公開前に実行する必要があります。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Confirm this OpenAI compatible API request is routed through Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)Python で重要なのは base_url です。きれいな OpenAI compatible API の移行では、アプリケーションコードは base URL が OpenAI を直接指しているのか、プロバイダー互換のエンドポイントなのか、あるいは Flatkey なのかを知るべきではありません。共有クライアントを呼び出し、どの経路を使うかは設定に任せるべきです。
ステップ5: Node の OpenAI SDK 設定を変更する
Node アプリでは、同等の設定として baseURL を使用します。
テンプレートのみ: 公開前にレビュー担当者が実行する必要があります。
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Confirm this OpenAI compatible API request is routed through Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);これは、各プロバイダーのドキュメント全体で見られるのと同じ移行パターンです。SDK はそのままにし、別のベース URL を設定し、互換性のある API キーを指定し、対象プラットフォームに存在するモデル ID を選択します。
ステップ6: モデルIDを意図的にマッピングする
多くのOpenAI互換API移行は、モデル文字列の部分で失敗します。ベースURLは互換であっても、モデルIDはプロバイダー固有のままの場合があります。
次のように仮定しないでください。
- 以前のモデル名がFlatkeyに存在する。
- プロバイダーのモデルエイリアスが、ゲートウェイの背後で同じバージョンを指している。
- 互換モデルはすべて同じエンドポイントファミリーをサポートしている。
- チャットで動くモデルは、ビジョン、ツール、画像、動画、またはResponsesでも動く。
その代わり、最初のアプリレベルのテストの前に次のマッピング表を使用してください。
| 現在のアプリ用途 | Flatkeyでの確認事項 |
|---|---|
| テキストチャット | OpenAIのチャットエンドポイントをサポートするFlatkeyモデルを選択します。 |
| ストリーミングチャット | 同じプロンプトとタイムアウト予算で、ストリーミングを別途テストします。 |
| ツール/関数呼び出し | 選択したモデルとエンドポイントが、アプリが送信するツール呼び出しの形式をサポートしていることを確認します。 |
| JSON出力 | 正確なresponse_formatまたは構造化出力パターンをテストします。 |
| Vision/画像入力 | 選択したモデルが、SDKが送信する画像入力形式を受け付けることを確認します。 |
| Responses API | Flatkeyのエンドポイント/モデルが、あなたのユースケースで/v1/responsesをサポートしていることを確認します。 |
| 画像または動画生成 | これはチャット補完の移行ではなく、別のエンドポイント移行として扱います。 |
2026年6月11日時点のFlatkeyの価格スナップショットでは、OpenAI chat completions、OpenAI Responses、Anthropic messages、Gemini、画像生成、OpenAI videoの各エンドポイントファミリーが示されていました。これはレビュー用の有用な証拠ですが、記事では、公開日に使う予定の正確なモデルと機能を確認するよう読者に促すべきです。
ステップ 7: ログ、クォータ、請求を確認する
OpenAI compatible API の応答に成功したことは、最初のチェックポイントにすぎません。Flatkey を通じて移行する理由は、単にリクエストの形状だけではなく、モデルアクセスを取り巻く運用面にあります。
スモークテストの後、次を確認してください:
| 領域 | 確認内容 |
|---|---|
| 使用ログ | リクエストがタイムスタンプ、モデル、トークン使用量、ステータス、必要に応じてエラー詳細とともに表示される。 |
| 請求 | コストが表示され、想定したモデル/料金単位と一致している。 |
| クォータ | 本格展開の前に、新しいキーまたはテストルートに小さなクォータを設定できる。 |
| ルーティング | リクエストが、古い直接プロバイダー設定ではなく、意図した Flatkey の経路を通ってルーティングされる。 |
| エラー動作 | 不正なキー、不正なモデル、未対応パラメーターのエラーが、サポート対応に十分なほど明確である。 |
| ロールバック | 以前のベース URL/モデルの復元が、コード変更なしで機能する。 |
ここで、OpenAI compatible API ゲートウェイは、単なるプロバイダーの生エンドポイントよりも有用になります。ベース URL の変更は、単に異なる上流先になるだけでなく、可視性の向上につながるべきです。
ステップ 8: 段階的に展開する
すべてのワークフローを一度に移行しないでください。段階的な展開を使います:
- 直接の curl スモークテストを実行します。
- ローカルまたはステージングで 1 つの SDK スモークテストを実行します。
- 既知の小さなプロンプトセットを再生し、出力の形状を比較します。
- 基本呼び出しが成功してから、ストリーミングまたは高度なパラメータを有効にします。
- テストキーに低いクォータを設定します。
- 少量の非重要トラフィックを送信します。
- エラー、レイテンシ、トークン使用量、コストを比較します。
- ログと請求が想定どおりに一致してから、トラフィックを増やします。
この流れにより、OpenAI compatible API の約束を本番の現実に結び付けたままにできます。互換性はスローガンではありません。実際にアプリが送信する呼び出しに対するテスト結果です。
移行チェックリスト
これは公開ページ用アセットとして使用してください。
| ステップ | 完了? | 備考 |
|---|---|---|
| 現在の SDK とエンドポイントが文書化されている | Python、Node、HTTP、wrapper、chat、responses、image、video など。 | |
| Flatkey キーが作成されている | 可能であれば別のテストキーを使用してください。 | |
| Base URL が一元管理されている | https://router.flatkey.ai/v1 は、コードの各所ではなく設定に置くべきです。 |
|
| Model ID が Flatkey から選択されている | 料金またはダッシュボードで公開日用の model ID を確認してください。 | |
| Curl のスモークテストに合格している | テンプレートは公開前にレビュー担当者によるテストが必要です。 | |
| Python または Node SDK のスモークテストに合格している | アプリが実際に実行している SDK を使用してください。 | |
| ストリーミング/ツール/JSON/ビジョン機能がテストされている | 使用する機能のみをテストしてください。 | |
| 使用ログが表示されている | ダッシュボードで model、status、tokens、errors を確認してください。 | |
| 請求と料金単位が確認されている | プロバイダーの料金単位が同一だと仮定しないでください。 | |
| クォータ制限が設定されている | 移行トラフィックを制限してください。 | |
| ロールバック用の環境変数が準備されている | 古い base URL と model をコード変更なしで復元できます。 |
よくある間違い
最も一般的なOpenAI互換APIの移行ミスは、ベースURLだけを変更して、他のすべての詳細も同じだと思い込むことです。次の落とし穴を避けてください:
- FlatkeyのベースURLを複数のファイルにハードコードする。
- Flatkeyがルーティングしない古いプロバイダのモデルIDを使い続ける。
- 本番ではストリーミングを使っているのに、非ストリーミングのみをテストする。
- tool-callやJSON出力のテストを省略する。
- 画像/動画エンドポイントを、あたかもchat-completionsエンドポイントであるかのように移行する。
- 再試行、タイムアウト予算、エラー解析の更新を忘れる。
- 使用状況と請求が見える前に移行完了と宣言する。
Flatkeyはプロバイダアカウントとルーティングの乱立を減らしますが、慎重な移行テストの必要性をなくすものではありません。
Flatkey が適している場合
Flatkey は、複数モデルへのアクセスのために個別のプロバイダーアカウント、キー、請求、ルーティング確認ではなく、1つの OpenAI compatible API ベース URL をチームで使いたい場合に最適です。
次のような場合に Flatkey を使ってください:
- アプリがすでに OpenAI compatible SDK を使用している。
- GPT、Claude、Gemini、DeepSeek、Qwen、Seedance 2.0、GPT Image など、プロバイダーをまたぐモデルに対して 1 つのキーを使いたい。
- 使用状況、請求、キー、ルーティングを 1 つのダッシュボードで確認したい。
- トラフィックが増える前にクォータ制限を設定したい。
- モデル切り替えとロードバランシングの挙動をゲートウェイ層で処理したい。
- 移行手順を「ベース URL を変更し、モデルを確認し、使用状況を監視する」にしたい。「モデル統合を書き直す」にしたくない。
プロバイダー固有の契約、完全にカスタムなルーティングロジック、またはインフラ内でのゲートウェイ制御が必要な場合は、直接プロバイダーのアカウントまたはセルフホストのプロキシを使用してください。
FAQ
OpenAI互換APIはOpenAIと同じですか？
いいえ。OpenAI互換APIは、対応エンドポイントについてOpenAIスタイルのリクエストおよびレスポンスのパターンに従いますが、提供元、モデルID、認証、機能サポート、価格、エラー挙動は異なる場合があります。
Flatkeyを使うためにSDKを置き換える必要はありますか？
一般的なチャット補完の移行では、通常は不要です。SDKがカスタムのベースURLをサポートしているなら、SDKはそのままで設定だけ変更できることがよくあります。これがOpenAI互換API移行の大きな利点です。
FlatkeyのOpenAI互換ベースURLは何ですか？
OpenAI互換ベースURLとして https://router.flatkey.ai/v1 を使用してください。チャット補完では、完全なエンドポイントは https://router.flatkey.ai/v1/chat/completions です。
既存のモデル名をそのまま使えますか？
そのモデルIDがFlatkey経由で利用可能かつサポートされている場合に限ります。pricing またはダッシュボードを確認し、展開前に正確なモデルIDでテストしてください。
Chat CompletionsとResponsesのどちらを先に移行すべきですか？
既存アプリが使用しているエンドポイントを移行してください。既存のChat Completionsアプリは /v1/chat/completions から始められます。アプリがResponses APIを使用している場合は、/v1/responses を別途テストし、選択したモデルが必要な機能をサポートしていることを確認してください。
ロールバックはどうすればよいですか？
Flatkeyのログ、コスト、クォータ、アプリケーションの挙動が確認できるまで、旧来のベースURL、APIキー、モデルを設定に保持してください。ロールバックはコードの書き換えではなく、環境変数の変更で行えるようにしておくべきです。
キーを取得する
すでにOpenAI compatible APIを中心に構築されたアプリがあるなら、Flatkeyなら移行は最小限です。キーを取得し、ベースURLを変更し、モデルを選び、スモークテストを実行し、1つのダッシュボードで使用状況を監視できます。
キーを取得する、そして最初のFlatkey移行テストではhttps://router.flatkey.ai/v1をベースURLとして使用してください。
