openrouter-api

OpenRouter API

OpenRouter は、300 以上の LLM を統合した API です。スキーマは /api/v1/chat/completions で OpenAI と互換性があり、OpenRouter 独自の拡張機能（models[]、provider、plugins、reasoning、cache_control、プリセット、:suffix ショートカット）も利用できます。認証には Authorization: Bearer <OPENROUTER_API_KEY> を使用します。

ベース URL と認証

POST https://openrouter.ai/api/v1/chat/completions
Authorization: Bearer $OPENROUTER_API_KEY
Content-Type: application/json

アトリビューションヘッダー（リーダーボードのランキングに反映）を任意で指定できます。

• HTTP-Referer: <YOUR_SITE_URL>
• X-OpenRouter-Title: <YOUR_SITE_NAME>（X-Title も使用できます）
• X-OpenRouter-Categories: <comma,separated>

API キーは https://openrouter.ai/keys で作成できます。各キーにはクレジット上限を設定でき、OAuth フローでも使用できます。OpenRouter は GitHub のシークレットスキャンパートナーです。漏えいした sk-or-... キーが検出されると、メールで通知されます。

3 つの連携方法

方法	パッケージ	最適な用途
生の HTTP	なし	あらゆる言語で使用でき、依存関係もありません
クライアント SDK	@openrouter/sdk（npm）／openrouter（pip）	REST を型安全に利用する軽量ラッパー
エージェント SDK	@openrouter/agent（npm のみ、TS）	callModel による複数ターンのループ、ツール実行、状態管理
OpenAI SDK	baseURL: https://openrouter.ai/api/v1 を指定した openai	既存の OpenAI コードへのドロップイン

通常は OpenRouter SDK を使用してください。ユーザーから明示的に求められた場合に限り、OpenAI SDK を参照してください。

クイックスタート（TS SDK）

import OpenRouter from '@openrouter/sdk';

const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const completion = await client.chat.send({
  model: 'openai/gpt-5.2',
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
});
console.log(completion.choices[0].message.content);

クイックスタート（Python SDK）

from openrouter import OpenRouter
import os

with OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY")) as client:
    response = client.chat.send(
        model="openai/gpt-5.2",
        messages=[{"role": "user", "content": "What is the meaning of life?"}],
    )
    print(response.choices[0].message.content)

クイックスタート（生の HTTP）

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.2","messages":[{"role":"user","content":"hi"}]}'

モデル識別子

形式：<provider>/<model>（例：anthropic/claude-sonnet-4.6、openai/gpt-5.2、google/gemini-3-flash-preview、meta-llama/llama-3.3-70b-instruct、deepseek/deepseek-v3.2）。すべてのモデルは https://openrouter.ai/models で確認できます。API から一覧を取得するには、GET /api/v1/models?supported_parameters=tools&output_modalities=text を使用します。

サフィックスショートカット

サフィックス	効果	同等の指定
:nitro	プロバイダーをスループット順に並べ替えます	provider.sort = "throughput"
:floor	プロバイダーを最低価格順に並べ替えます	provider.sort = "price"
:online	Web プラグインを有効にします（非推奨 — openrouter:web_search サーバーツールを推奨）	openrouter/auto と plugins: [{id: "web"}]
:free	無料プランのモデル（レート制限あり、日次上限あり）	—

組み合わせて使用できます：openai/gpt-oss-20b:free:online。

特別なモデルスラッグ

• openrouter/auto — Auto Router（NotDiamond によるプロンプト対応型のモデル選択）
• openrouter/bodybuilder — 自然言語から、複数モデルへの並列ファンアウト用の構造化されたリクエストボディを生成します（無料）
• @preset/<slug> — 名前を指定して、保存済みのプリセット（システムプロンプト + パラメーター + プロバイダールール）を呼び出します。設定場所：https://openrouter.ai/settings/presets。preset: "<slug>" フィールド、または model: "openai/gpt-4@preset/<slug>"（組み合わせて指定）としても使用できます。リクエストごとのパラメーターは、プリセット設定に対してシャローマージされます。

リクエストボディ — トップレベルの構造

type Request = {
  // Either messages or prompt
  messages?: Message[];
  prompt?: string;

  model?: string;           // omit = user default
  models?: string[];        // model fallbacks in order

  stream?: boolean;
  stop?: string | string[];
  response_format?: ResponseFormat;       // json_object | json_schema
  tools?: Tool[];
  tool_choice?: ToolChoice;
  parallel_tool_calls?: boolean;          // default true

  // OpenRouter-only
  provider?: ProviderPreferences;         // see references/routing.md
  plugins?: Plugin[];                     // web, file-parser, response-healing, context-compression, auto-router
  reasoning?: ReasoningConfig;            // see references/reasoning.md
  preset?: string;
  user?: string;                          // stable end-user ID for abuse detection
  debug?: { echo_upstream_body?: boolean }; // streaming only

  // Standard sampling — see references/api-reference.md
  max_tokens?: number;
  temperature?: number;
  top_p?: number; top_k?: number; min_p?: number; top_a?: number;
  frequency_penalty?: number; presence_penalty?: number; repetition_penalty?: number;
  seed?: number; logit_bias?: Record<number, number>;
  logprobs?: boolean; top_logprobs?: number;
  prediction?: { type: 'content'; content: string };
  verbosity?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
};

選択したモデルでサポートされていないパラメーターは、残りのパラメーターが上流に転送される一方で、通知なく無視されます。すべてのパラメーターをサポートするプロバイダーを必須にするには、provider.require_parameters: true を設定します。

レスポンスの構造

{
  "id": "gen-xxxxxxxxxxxxxx",
  "model": "openai/gpt-4o",
  "object": "chat.completion",
  "choices": [{
    "finish_reason": "stop",
    "native_finish_reason": "stop",
    "message": { "role": "assistant", "content": "Hello there!" }
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14,
    "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "cost": 0.00014
  }
}

ストリーミングチャンクでは message の代わりに delta が使われ、object は "chat.completion.chunk" になります。data: [DONE] の前の最終チャンクには usage が含まれ、choices は空になります。

finish_reason は tool_calls、stop、length、content_filter、error のいずれかに正規化されます。プロバイダーの生の値は native_finish_reason に格納されます。生成 ID は X-Generation-Id レスポンスヘッダーにも返されます。

エラー

{ "error": { "code": 400, "message": "...", "metadata": { ... } } }

コード	意味
400	不正なリクエスト／無効なパラメーター／CORS
401	無効な API キー／OAuth の有効期限切れ
402	クレジット不足 — クレジットを追加してください
403	モデレーションにより入力がフラグ付けされました
408	リクエストがタイムアウトしました
429	レート制限に達しました
502	上流のモデルがダウンしている、またはレスポンスが無効です
503	ルーティング要件を満たすプロバイダーがありません

ストリーム中のエラー（HTTP 200 がすでに送信された後に発生）は、トップレベルに error を含み、finish_reason: "error" を持つ選択肢を含む最終 SSE チャンクとして返されます。streaming.md を参照してください。

機能一覧

機能	トリガー	リファレンス
サンプリングパラメーター、リクエスト／レスポンスの完全なスキーマ、デバッグオプション	チャット呼び出し全般	references/api-reference.md
SSE ストリーミング、キャンセル、ストリーミング中のエラー	stream: true	references/streaming.md
関数／ツール呼び出し、エージェントループ、並列ツール、ストリーミングツール呼び出し、MCP から OpenAI への変換	tools: [...]	references/tool-calling.md
構造化出力（json_schema、json_object）	response_format	references/structured-outputs.md
推論／思考トークン（労力、max_tokens、除外）	reasoning: {...}	references/reasoning.md
プロンプトキャッシュ（自動、cache_control、スティッキールーティング）	cache_control または対応プロバイダー	references/prompt-caching.md
プロバイダーのルーティング（並べ替え、順序、限定、無視、max_price、スループット、ZDR）	provider: {...}	references/routing.md
モデルフォールバック、自動ルーター、ボディビルダー、プリセット	models[]、openrouter/auto、@preset/...	references/routing.md
マルチモーダル — 画像、PDF、音声、動画、画像生成、TTS	image_url/file/input_audio コンテンツパーツ	references/multimodal.md
プラグイン — web、file-parser、response-healing、context-compression、auto-router	plugins: [...]	references/plugins.md
openrouter:web_search サーバーツール、:online ショートカット、引用アノテーション	tools: [{type:'openrouter:web_search'}]	references/web-search.md
使用量の記録、コスト、/generation、キー／クレジット、レート制限	usage フィールド、GET /api/v1/key	references/usage-and-limits.md
BYOK プロバイダーキー、OAuth PKCE、アプリの帰属情報	/settings/integrations で設定する cbat_ 形式のプロバイダーキー	references/byok-and-oauth.md

常に最新のドキュメント

OpenRouter では、URL に .md を追加すると任意のドキュメントページの Markdown を取得できます。また、セクションごとに集約された llms-full.txt ファイルも利用できます。特定のエッジケースについて、ここにあるリファレンス資料では不十分な場合は、次の最新情報を取得してください。

• クイックスタート：https://openrouter.ai/docs/quickstart/llms-full.txt
• API リファレンス：https://openrouter.ai/docs/api/reference/llms-full.txt
• 機能：https://openrouter.ai/docs/guides/features/llms-full.txt
• ルーティング：https://openrouter.ai/docs/guides/routing/llms-full.txt
• プラグイン：https://openrouter.ai/docs/guides/features/plugins/llms-full.txt
• マルチモーダル：https://openrouter.ai/docs/guides/overview/multimodal/llms-full.txt
• ベストプラクティス（キャッシュ、推論）：https://openrouter.ai/docs/guides/best-practices/llms-full.txt
• 認証（BYOK、OAuth）：https://openrouter.ai/docs/guides/overview/auth/llms-full.txt
• 管理（使用量の記録）：https://openrouter.ai/docs/guides/administration/llms-full.txt
• サーバーツール（ウェブ検索）：https://openrouter.ai/docs/guides/features/server-tools/llms-full.txt
• OpenAPI 仕様：https://openrouter.ai/openapi.yaml または .json

単一ページの Markdown を取得するには、任意のドキュメント URL に .md を追加してください。

よくある落とし穴

• prompt と messages は相互に排他的です — どちらか一方を選んでください。
• エージェント型のループでは、各ターンで tools 配列を繰り返し指定する必要があります。 ルーターは呼び出しごとにスキーマを検証します。ツール結果メッセージの前に、アシスタントのツール呼び出しメッセージを履歴に追加し忘れると、Anthropic モデルで問題が発生します。
• Anthropic の自動キャッシュ（トップレベルの cache_control）は Anthropic プロバイダーにのみルーティングされます — Bedrock と Vertex AI は対象外です。ブロック単位の cache_control は 3 つすべてで機能します。
• max_tokens の上限は context_length - prompt_length です。無制限ではありません。
• OpenAI o-series と一部の推論モデルは、内部で生成されていても推論トークンを返しません。 reasoning.exclude: true が制御するのは表示であり、内部での使用ではありません。
• debug.echo_upstream_body は stream: true の場合にのみ機能し、開発専用です — リクエストの内部情報が漏れる可能性があります。
• :online ショートカットは、openrouter/auto 経由でルーティングされる非推奨の web プラグインです。 新しいコードでは openrouter:web_search サーバーツールを使用し、検索するタイミングをモデルが判断できるようにします。
• ストリーム途中のエラーでも HTTP 200 のままです。これはヘッダーがすでに送信されているためです。チャンクのトップレベルにある error フィールドと finish_reason: "error" で検出してください。
• BYOK キーは、provider.order に関係なく、OpenRouter の共有容量より常に先に試されます。
• 無料枠（:free）のレート制限はアカウントごとに共通です — API キーを追加してもクォータは増えません。
• usage: { include: true } と stream_options: { include_usage: true } のパラメーターは非推奨です — 現在は使用量が常に含まれます。