OpenAI から RouteAPI への移行

このガイドは、既存の OpenAI アプリケーションを RouteAPI に移行する手順を説明します。ほとんどの場合、Base URL と API Key の変更だけで、他のコードはそのままで動作します。

RouteAPI に移行する理由

RouteAPI は OpenAI との互換性を保ちながら、より多くの機能を提供します：

• 複数プロバイダーへの統一アクセス - OpenAI に加えて、Claude、Gemini、Azure、AWS Bedrock などのモデルをコード変更なしで利用可能
• コスト管理と予算制御 - 複数モデルの使用量と割り当てを一元管理し、予算超過を防止
• 可観測性の強化 - 統一されたリクエストログ、使用量統計、パフォーマンス監視
• 高可用性とロードバランシング - 自動フェイルオーバーとマルチチャネル負荷分散
• 柔軟な権限と割り当て - チーム、プロジェクト、環境ごとに独立したトークンと制限を作成

移行難易度の評価

シナリオ	変更範囲	想定時間
OpenAI SDK（Python/Node.js）を使用	初期化設定の変更のみ（2行のコード）	< 5分
LangChain/LiteLLM などのフレームワークを使用	設定パラメータの変更	< 10分
Cursor/Claude Code などのクライアントを使用	設定パネルで Base URL と Key を変更	< 5分
HTTP リクエストを直接使用	リクエスト URL と認証ヘッダーを変更	< 10分

基本設定の変更

移行の核心は、2つの設定項目を変更することです：

1. Base URL の変更

OpenAI の Base URL を RouteAPI に置き換えます：

# OpenAI の元の URL
https://api.openai.com/v1

# RouteAPI の URL
https://api.routeapi.ai/v1

2. API Key の置き換え

OpenAI API Key を RouteAPI トークンに置き換えます：

1. RouteAPI コンソール にログイン
2. API Keys ページで新しいトークンを作成
3. トークンをコピーして保存（形式：sk-...）

3. 環境変数による管理

認証情報は環境変数で管理することを推奨します：

# .env ファイル
ROUTEAPI_KEY=sk-your-routeapi-token

セキュリティのヒント：トークンをバージョン管理にコミットしないでください。.gitignore で .env ファイルを除外してください。

Python SDK の移行

OpenAI SDK

base_url と api_key パラメータのみを変更します：

# 移行前 - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # OpenAI Key
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)

# 移行後 - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # RouteAPI トークンを使用
    base_url="https://api.routeapi.ai/v1",  # RouteAPI を指定
)

response = client.chat.completions.create(
    model="gpt-4",  # または claude-3-5-sonnet-20241022 などの他のモデル
    messages=[{"role": "user", "content": "Hello"}],
)

変更点：

• base_url パラメータを追加
• api_key を置き換え、環境変数から読み取ることを推奨
• オプション：model を RouteAPI がサポートする他のモデルに変更

LangChain の設定

# 移行前
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# 移行後
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

LiteLLM の設定

# 移行前
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# 移行後
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Node.js SDK の移行

OpenAI SDK

初期化設定のみを変更します：

// 移行前 - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // OpenAI Key
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
});

// 移行後 - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // RouteAPI トークンを使用
  baseURL: 'https://api.routeapi.ai/v1',  // RouteAPI を指定
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // または claude-3-5-sonnet-20241022 などの他のモデル
  messages: [{ role: 'user', content: 'Hello' }],
});

変更点：

• baseURL パラメータを追加
• apiKey を置き換え、環境変数から読み取ることを推奨
• オプション：model を RouteAPI がサポートする他のモデルに変更

クライアントツールの移行

IDE クライアントやコーディングエージェントを使用している場合、設定パネルで設定を変更するだけです：

クライアント	設定ガイド
Cursor	Cursor 設定
Claude Code	Claude Code 設定
OpenCode	OpenCode 設定
Codex (oh-my-codex)	Codex 設定

通常、以下の2項目のみを変更します：

1. Base URL / API Endpoint → https://api.routeapi.ai/v1
2. API Key → あなたの RouteAPI トークン

パラメータの互換性確認

変更不要なパラメータ

以下のパラメータは RouteAPI で OpenAI と同じ動作をします：

• model - モデル ID
• messages - 会話メッセージ配列
• temperature - ランダム性の制御（0-2）
• max_tokens - 生成する最大トークン数
• top_p - ニュークリアスサンプリングパラメータ
• frequency_penalty - 頻度ペナルティ
• presence_penalty - 存在ペナルティ
• stop - 停止シーケンス
• stream - ストリーミングレスポンスを有効にするか
• user - エンドユーザー識別子
• n - 返される結果の数

注意が必要なパラメータ

一部のパラメータのサポートは、選択したモデルの機能に依存します：

パラメータ	説明	依存関係
tools / tool_choice	ツール呼び出し（Function Calling）	モデルがツール呼び出しをサポートする必要がある
response_format	構造化出力（JSON mode）	モデルが JSON 出力をサポートする必要がある
seed	決定論的サンプリングシード	一部のモデルでサポート
logprobs / top_logprobs	トークン確率を返す	一部のモデルでサポート

推奨：高度なパラメータについては、テスト環境で対象モデルがサポートしているか最初に確認してください。

明示的なゼロ値の処理

RouteAPI は Rule 5 の規約に従います：

• クライアントが temperature=0、top_p=0、または max_tokens=0 を明示的に渡した場合、これらの値はそのまま上流モデルに転送されます
• 「未設定」として無視されることはありません

つまり、temperature=0 を使用して決定論的な出力を得ることができます。

モデル名

利用可能なモデルのクエリ

移行後、OpenAI 以外のさらに多くのモデルにアクセスできます。/v1/models エンドポイントを使用してクエリします：

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

レスポンス例：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...さらに多くのモデル
  ]
}

モデル ID の使用

重要：リクエスト時にはモデルの id フィールド（例：claude-3-5-sonnet-20241022）を使用してください。表示名（例：「Claude 3.5 Sonnet」）は使用しないでください。

# ✅ 正しい - モデル ID を使用
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ 間違い - 表示名を使用
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # エラーになります
    messages=[...],
)

クロスプロバイダーモデルの切り替え

RouteAPI に移行後、異なるプロバイダーのモデルを簡単に試すことができます：

# OpenAI モデル
model="gpt-4"
model="gpt-4o"

# Anthropic Claude モデル
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Google Gemini モデル
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# AWS Bedrock モデル（RouteAPI 経由）
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

model パラメータを変更するだけで、他のコードは変更不要です。

テストと検証

テストチェックリスト

移行完了後、以下のチェックリストで検証することを推奨します：

• 認証テスト - トークンが有効で、/v1/models を正常に呼び出せることを確認
• 基本的な呼び出し - chat.completions.create が正常に返されることをテスト
• ストリーミングレスポンス - stream=True を使用している場合、ストリーミング出力が正常に動作することを確認
• ツール呼び出し - Function Calling を使用している場合、ツール呼び出しフローを確認
• エラー処理 - 残高不足、レート制限、無効なパラメータなどのエラーシナリオをテスト
• 使用量統計 - RouteAPI コンソールで使用量ログが正しく記録されているか確認

よくあるトラブルシューティング

エラーコード	よくある原因	解決方法
401 Unauthorized	トークンが無効または欠落	Authorization ヘッダー形式を確認：Bearer sk-...
402 Payment Required	残高不足または割り当て超過	コンソールにログインしてチャージするか、トークン割り当てを増やす
404 Not Found	Base URL が間違っているかパスのスペルミス	Base URL が https://api.routeapi.ai/v1 であることを確認
429 Too Many Requests	レート制限に達した	リクエスト頻度を下げるか、管理者に連絡して制限を増やす
500 Internal Server Error	上流モデルサービスの異常	リクエストを再試行するか、バックアップモデルに切り替える

デバッグのヒント：

• cURL を使用して API を直接テストし、SDK 設定の問題を排除
• RouteAPI コンソールの使用量ログで具体的なエラーメッセージを確認
• 元の OpenAI リクエストと RouteAPI リクエストのパラメータの違いを比較

例：cURL でテスト

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

cURL リクエストが成功した場合、トークンと Base URL の設定が正しく、問題は SDK レイヤーにある可能性があります。

段階的な移行の推奨事項

本番環境では、段階的な移行戦略を推奨します：

1. まずテスト環境で検証

• 開発環境またはテスト環境で移行後のコードを完全にテスト
• コア機能、境界ケース、エラー処理を検証
• OpenAI と RouteAPI のレスポンス内容とパフォーマンスを比較

2. 段階的なロールアウト

• フィーチャーフラグを使用して Base URL の切り替えを制御
• 最初は少量のトラフィックで RouteAPI を有効化
• エラー率、レイテンシー、ユーザーフィードバックを観察

例：環境変数で制御

import os

# 環境変数で RouteAPI を使用するかどうかを制御
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. 使用量ログとエラー率の監視

移行後は以下を注意深く監視してください：

• リクエスト成功率 - 異常な 4xx/5xx エラーの有無
• レスポンスレイテンシー - P50、P95、P99 のレイテンシー分布
• トークン使用量 - 請求が予想通りか
• モデルの可用性 - 異なるモデルの成功率とレイテンシー

RouteAPI コンソールの「使用量ログ」ページで詳細な記録を確認できます。

4. ロールバックプラン

OpenAI への迅速なロールバックプランを準備してください：

• 元の OpenAI API Key を保持し、すぐに削除しない
• 設定センターまたは環境変数で Base URL を管理し、迅速な切り替えを可能に
• 監視にアラート閾値を設定し、自動的にロールバックをトリガー

# ロールバック例：環境変数を変更するだけで切り替え
# USE_ROUTEAPI=false -> OpenAI を使用
# USE_ROUTEAPI=true -> RouteAPI を使用

移行後の最適化の推奨事項

1. マルチモデル機能の活用

RouteAPI は複数のプロバイダーのモデルをサポートしています。シナリオに応じて最適なモデルを選択してください：

• レイテンシーに敏感なシナリオ - gemini-2.0-flash-exp または gpt-4o-mini を使用
• 複雑な推論タスク - claude-3-5-sonnet-20241022 または gpt-4 を使用
• コスト最適化 - 異なるモデルのコストパフォーマンスを比較し、最適なソリューションを選択

2. 独立したトークンの設定

プロジェクト、環境、チームごとに独立したトークンを作成してください：

• 開発環境 - 低割り当てトークンで、テスト時の大量の費用を避ける
• 本番環境 - 高割り当てトークンで、アラートを設定
• 異なるチーム - 独立したトークンでコストの帰属と監査を容易に

3. リクエストログの有効化

RouteAPI コンソールで詳細なリクエストログを確認してください：

• 各リクエストのモデル、トークン使用量、レイテンシー
• エラーリクエストの理由とスタック
• 使用量トレンドとコスト分析

これらのログはコストの最適化と問題のトラブルシューティングに役立ちます。

ヘルプの入手

移行中に問題が発生した場合：

• API リファレンスドキュメント を参照
• RouteAPI コンソール で使用量ログを確認
• テクニカルサポートに連絡してサポートを受ける

---

関連ドキュメント：

• API 概要
• 認証
• Chat Completions API
• OpenAI SDK 統合