mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 12:52:25 +03:00

Files

Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940 )

1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732

2026-09-17 02:55:31 -03:00

139 KiB

Raw Blame History

API Reference (日本語)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

OmniRoute API の主要リファレンスです。公開されている /v1 インターフェースと、最もよく使用される管理エンドポイントを取り上げています。網羅的な情報源については、機械可読な docs/openapi.yaml と src/app/api/ 配下のルートツリーを参照してください。

チャット補完
排他的マネージドセッションリース
埋め込み
画像生成
ドキュメントOCR
モデル一覧
プロバイダープラグインマニフェスト
互換性エンドポイント
Files API
Batches API
Search API
WebSocketストリーミング
クォータと問題の報告
セマンティックキャッシュ
ダッシュボードと管理
コンボ管理
Webhook
登録済みキー（自動管理）
エージェントプロトコル
管理プロキシ
耐障害性（拡張）
スキル
メモリ
MCPサーバー
A2Aサーバー
クラウド、評価、アセスメント
リクエスト処理
認証

チャット補完

POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "関数を作成してください..."}
  ],
  "stream": true
}

カスタムヘッダー

ヘッダー	方向	説明
`X-OmniRoute-No-Cache`	リクエスト	キャッシュをバイパスするには`true`に設定します
`x-omniroute-no-memory`	リクエスト	このリクエストでメモリとスキルの注入をスキップするには`true`に設定します（no-cacheと同様に動作し、呼び出しごとのトークン／コストのオーバーヘッドを回避します）
`X-OmniRoute-Progress`	リクエスト	進捗イベントを有効にするには`true`に設定します
`X-Session-Id`	リクエスト	外部セッションアフィニティ用の固定セッションキー
`x_session_id`	リクエスト	アンダースコア形式も受け付けます（直接HTTP通信）
`X-OmniRoute-Session-Id`	リクエスト	呼び出し元が指定するセッション／会話タグ（メモリにも渡されます）。指定された場合、セッションごとのコスト帰属用に、そのまま`call_logs.session_tag`へ永続化されます（#8249）。指定されていない場合は生成されません
`Idempotency-Key`	リクエスト	重複排除キー（5秒間のウィンドウ）
`X-Request-Id`	リクエスト	代替の重複排除キー
`X-OmniRoute-Cache`	レスポンス	`HIT`または`MISS`（非ストリーミング）
`X-OmniRoute-Idempotent`	レスポンス	重複排除された場合は`true`
`X-OmniRoute-Progress`	レスポンス	進捗追跡が有効な場合は`enabled`
`X-OmniRoute-Session-Id`	レスポンス	OmniRouteが使用した実効セッションID
`X-OmniRoute-Request-Id`	レスポンス	リクエスト相関ID（判明している場合）
`X-OmniRoute-Version`	レスポンス	OmniRouteのビルドバージョン（常に含まれます）
`X-OmniRoute-Cost-Saved`	レスポンス	HITによってキャッシュが節約した金額（USD、キャッシュヒット時のみ）
`X-OmniRoute-Decision`	レスポンス	ルーティングトレース：`strategy=<name>; provider=<alias>; latency_ms=<n>`（`<name>`はコンボ戦略、コンボ以外のリクエストでは`single`）。完了レスポンスには常に含まれます

Nginxに関する注記：アンダースコアを含むヘッダー（例：x_session_id）を利用する場合は、underscores_in_headers on;を有効にしてください。

コストテレメトリヘッダー: 非ストリーミングの成功レスポンスには、X-OmniRoute-* コストテレメトリセットも含まれます。これには、X-OmniRoute-Response-Cost（USD、固定小数点以下10桁。無料または価格未設定の場合は 0.0000000000）、X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out、X-OmniRoute-Model、X-OmniRoute-Provider、X-OmniRoute-Latency-Ms、X-OmniRoute-Cache-Hit、X-OmniRoute-Fallback-Attempts（0より大きい場合のみ）、さらに X-OmniRoute-Request-Id と X-OmniRoute-Version が含まれます。これらは、チャット補完、/v1/responses、/v1/messages、およびメディアエンドポイント（/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/rerank、/v1/videos/generations、/v1/music/generations、/v1/moderations（コストは常に 0））から出力されます。メディアのコストは、価格情報が利用可能な場合はモダリティごと（画像単位、秒単位、文字単位、検索単位）に計算され、それ以外の場合は 0 になります（フェイルオープン）。

キャッシュヒット時のコストのセマンティクス: セマンティックキャッシュのヒット時（X-OmniRoute-Cache-Hit: true）にはアップストリーム呼び出しが行われないため、X-OmniRoute-Response-Cost は 0.0000000000（ヒットを提供するための増分コスト）になります。元のコスト、つまりキャッシュがなければ発生していたはずのコストは、X-OmniRoute-Cost-Saved で別途報告されます。請求処理を行うコンシューマーは X-OmniRoute-Response-Cost を合計してください（ヒットのコストはゼロです）。キャッシュ分析では、X-OmniRoute-Cost-Saved を集計できます。

排他的マネージドセッションリース

排他的マネージドセッションリースは、オプトイン方式のクライアント中立なルーティング契約です。1つのアクティブな所有者が、適格なOmniRoute接続を1つ保持します。モデルをリースするものではなく、OAuthを必要とせず、特定のクライアントを識別せず、特定のプロバイダーも必要としません。

認証に使用するAPIキーには、スコープlease:exclusiveと、明示的かつ空でないallowedConnectionsリストが必要です。データベースのミューテーション境界では、キーの作成時および部分更新時に、これら両方のフィールドがまとめて強制されます。

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

取得、更新、解放に成功したレスポンスでは、タイムスタンプ、state、および正確な正のgenerationが公開されますが、選択された接続や認証情報は決して公開されません。更新と解放では、JSON本文でgenerationを指定します。

{ "action": "renew", "generation": 1 }

{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

アクティブなリース所有者は、現在のバインディングについて、プライバシーに配慮した表示メタデータを明示的に要求できます。

{ "action": "status", "generation": 1 }

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

このオプトインのstatusアクションは、単一のデータベーストランザクション内で、不透明な所有者、認証済みのマネージドAPIキー、および正確なアクティブgenerationによってフェンシングされます。displayNameは、設定された接続名をトリミングしたものに限られ、安全な設定済み名称が存在しない場合はnullになります。OmniRouteがメールアドレスや生成されたアカウントIDを代用することはありません。プロバイダー値は機密性のない表示ラベルであり、生成された互換プロバイダー識別子ではありません。認証情報、トークン、Cookie、生の接続IDまたはAPIキーID、所有者ハッシュ、フェンシングシークレット、および内部ルーティングデータは除外されます。

誤ったキー、誤った所有者、古いgeneration、存在しない、期限切れ、解放済み、無効化済みのいずれの検索も、接続メタデータを含まない同一の409 LEASE_FENCE_STALEエラーを返します。容量待機レスポンスを受け取ったクライアントには、確認可能なアクティブなバインディングがありません。ルーティングによってアクティブなリースが移行した場合も、同じgenerationが有効なままとなり、statusは古いバインディングではなく新しいバインディングをアトミックに返します。取得、更新、解放、および待機レスポンスは従来の形式を維持するため、既存のクライアントには影響しません。

このサーバー契約によって、標準のOpenAI Codex /statusが変更されることはありません。現在、標準のCodexはモデルプロバイダーと組み込みの認証／アカウント状態を報告しますが、任意のカスタムプロバイダーのアカウントメタデータは表示しません。今後のクライアント統合では、このアクションを呼び出し、connection.displayNameの表示方法を決定する必要があります。

以降、マネージド推論リクエストごとに、次の両方の制御ヘッダーを指定します。

X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1

サポート対象の各アップストリーム試行の直前に、正確な所有者、generation、アクティブな接続、および認証済みAPIキーがフェンシングされます。別のキーが同じ接続を許可している場合でも、そのキーで所有者とgenerationを再利用すると失敗します。生の所有者情報が永続化、ログ記録、リクエストスナップショットへの保持、またはアップストリームへの転送の対象になることはありません。

一時的な競合が発生した場合、HTTP 429がRetry-Afterおよび次の内容とともに返されます。

{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}

このレスポンスが意味するのは、通常の適格セットが空ではなく、空いている候補がすべて別のアクティブなリースによって保持されていたということだけです。サポートされていないモデル／プロバイダー、ポリシーの不一致、クールダウン、クォータ、正常性、およびその他の通常の適格性エラーでは、既存のOmniRouteレスポンスが維持されます。

`x-omniroute-compression`

リクエスト単位で圧縮プランを上書きします。優先順位は最も高く、ルーティングコンボの上書き、アクティブプロファイル、自動トリガー、およびパネルのDefaultより優先されます。値は次のとおりです。

値	効果
`off`	このリクエストでは圧縮しません。
`default`	パネルから派生したDefaultプロファイルを使用します（アクティブプロファイルは無視されます）。
`engine:<id>`	有効な場合に単一のエンジンを使用します（例：`engine:rtk`）。
`<combo>`	名前付きコンボ。最初に名前（大文字と小文字を区別しない）、次にidで照合されます。

注意事項：

不明な値は無視され（リクエストが拒否されることはありません）、解決処理は通常のオペレーター優先順位にフォールスルーします。
複数のコンボが同じ名前を共有する場合、決定的に照合するにはコンボのidを渡してください。
名前がoffまたはdefaultのコンボは、名前では選択できません（これらのキーワードが先に解釈されます）。そのようなコンボはidで参照してください。
マスター圧縮スイッチは強制的なゲートです。圧縮がグローバルに無効になっている場合、このヘッダーで有効にすることはできません。

適用されたプランは、次のレスポンスヘッダーで返されます。

X-OmniRoute-Compression: <mode>; source=<source>

ここで、<source>はrequest-header、routing-override、active-profile、auto-trigger、default、またはoffのいずれかです。

埋め込み

POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}

利用可能なプロバイダー: Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、OpenRouter、Jina AI。

カタログ ID は provider/model 形式です（例: jina-ai/jina-embeddings-v5-omni-small）。レジストリに存在する、プロバイダー名の付いていない Jina モデル ID（例: jina-embeddings-v5-text-small、jina-reranker-v3.5）も解決されます。Jina の embed/rerank/classify/segment では、まずダッシュボードの jina-ai 認証情報が使用されます。JINA_AI_API_KEY は、ダッシュボードキーが存在しない場合にのみフォールバックとして使用されます。jina-reader カードは Reader / r.jina.ai 専用（POST /v1/web/fetch）であり、埋め込みやリランキングには使用されません。

マルチモーダル対応を明示しているレジストリモデルでは、プロバイダーに依存しない構造化アイテムを最大 32 件まで受け付けます。メディアアイテムの種類は text、image、audio、video、document です。メディアの source は、{"type":"url","url":"https://..."} または {"type":"base64","data":"...","media_type":"..."} のいずれかです。

Jina v5 Omni（jina-ai/jina-embeddings-v5-omni-small、jina-ai/jina-embeddings-v5-omni-nano、およびファミリーエイリアス jina-ai/jina-embeddings-v5-omni → omni-small）は、Jina ネイティブの EmbeddingsV5Request ドキュメントも受け付け、それらをそのまま https://api.jina.ai/v1/embeddings に転送します。

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

ネイティブの { image | audio | video | pdf } 値には、公開 HTTPS URL、data: URI、または未加工の base64 を使用できます。OmniRoute はこれらのオブジェクトを文字列化せず、ネイティブ画像 URL も取得しません。公開メディアは Jina 自身が取得します。追加の Jina フィールド（task、normalized、truncate、embedding_type）も転送されます。テキスト専用の Jina SKU では、引き続きテキスト以外のドキュメントが拒否されます。

セキュリティおよび転送上の制限:

リモートメディア URL は公開 HTTPS である必要があります。正規形式の {type,source:url} アイテムはサーバー側で取得され（リダイレクトの再検証、タイムアウト、サイズ制限、公開 DNS、接続先の固定を実施）、プロバイダー呼び出しの前にインライン化されます。Jina ネイティブの {image:"https://..."} アイテムは、同じ公開 HTTPS チェック後にそのまま転送され、Jina が URL を取得します。
インライン base64 メディアは、デコード後のサイズでアイテムあたり 8 MiB、リクエスト全体で 16 MiB に制限されます。

プロバイダー向けの変換（正規形式のアイテムが変更されずに転送されることはありません）:

Jina マルチモーダルモデル: 各トップレベルアイテムは、インラインメディアに data URI を使用した、モダリティをキーとする単一のオブジェクト（text / image / audio / video / pdf）になります。トップレベルアイテムごとに 1 つのベクトルが生成されます。
Gemini Embedding 2 ファミリー: 1 つのトップレベル配列は、content.parts（text または inline_data）を持つ単一のネイティブ models/{model}:embedContent リクエストになります。
明示的なモダリティメタデータを持たない不明なモデルまたは動的モデルでは、構造化入力が HTTP 400 で拒否されます。

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

サポートされていないモデルとモダリティの組み合わせでは、アイテムを強制変換せずに HTTP 400 が返されます。従来の文字列／トークンリクエストに含まれる入力以外の拡張フィールドは、引き続き変更されずにそのまま渡されます。

# すべての埋め込みモデルを一覧表示
GET /v1/embeddings

画像生成

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "山々に沈む美しい夕日",
  "size": "1024x1024"
}

利用可能なプロバイダー: OpenAI (GPT Image 2)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI、Nebius (FLUX)、Hyperbolic、NanoBanana、OpenRouter、SD WebUI (ローカル)、ComfyUI (ローカル)。

# すべての画像モデルを一覧表示
GET /v1/images/generations

ドキュメントOCR

POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

model は、provider/model プレフィックスを使用してOCRプロバイダーを選択します。プロバイダーを含まないモデルID（例: mistral-ocr-latest）は登録済みのプロバイダーに解決され、model を省略した場合はデフォルトで Mistral（mistral-ocr-latest）が使用されます。登録済みプロバイダー（open-sse/config/ocrRegistry.ts）:

プロバイダーID	モデルID	`model` の値	備考
`mistral`	`mistral-ocr-latest`	`mistral/mistral-ocr-latest`（または `mistral-ocr-latest`）	同期式 — 単一のアップストリーム呼び出しからレスポンスが直接返されます。
`azure-document-intelligence`	`prebuilt-read`	`azure-document-intelligence/prebuilt-read`	非同期アップストリーム（`analyze` + ポーリング）— 以下を参照してください。
`vertex-deepseek-ocr`	`deepseek-ocr-maas`	`vertex-deepseek-ocr/deepseek-ocr-maas`	Vertex AIの`openapi/chat/completions`パートナーエンドポイント経由の同期式 — 認証/URLについては以下を参照してください。

3つのプロバイダーはすべて、同じMistral形式の本文で応答します:

{
  "pages": [{ "index": 0, "markdown": "# 抽出されたテキスト..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Azure Document Intelligenceのポーリングフロー

Azure Document Intelligenceのanalyze APIは非同期です。最初のリクエストでは本文の代わりに Operation-Locationヘッダーが返されるため、結果をポーリングする必要があります。ハンドラー（open-sse/handlers/ocr.ts）は、そのURLを1秒ごとに最大30回ポーリングします。ポーリングレスポンスがokでない場合、またはステータスが"failed"の場合は即座に失敗し（ポーリングを継続せず）、試行回数の上限に達した後も処理が実行中の場合は504を返します。Azureの最終レスポンスは、呼び出し元へ返される前に、Mistralで使用されるものと同じpages/markdown形式へ正規化されるため、クライアントコードでプロバイダーごとの特別な処理を行う必要はありません。

Vertex AI DeepSeek OCRの認証とエンドポイント解決

vertex-deepseek-ocrは、OmniRouteがチャット/画像トラフィック向けにすでにサポートしているものと同じ Vertex AI認証（open-sse/executors/vertex.ts）を再利用します。接続のAPIキーには、 Service Account JSON認証情報（JWTベアラーフローを介して短期間有効なOAuthアクセストークンと交換される）、または発行済みのOAuthアクセストークンをそのまま使用できます。アップストリームエンドポイントURLは、接続のプロジェクトとリージョンから構築される、Vertexの汎用openapi/chat/completionsパートナーエンドポイントです。明示的なproviderSpecificData.project/providerSpecificData.regionが常に優先されます。それ以外の場合、プロジェクトはService Account JSONのproject_idから取得され、リージョンのデフォルトは us-central1です。どちらの解決もopen-sse/handlers/ocr.ts （resolveVertexOcrAccessToken、resolveVertexOcrBaseUrl）で行われ、 handleOcrへ処理を渡す前にsrc/app/api/v1/ocr/route.tsによって使用されます。

モデル一覧

GET /v1/models
Authorization: Bearer your-api-key

→ すべてのチャット、埋め込み、画像モデル、および組み合わせを OpenAI 形式で返します

モデル ID のプレフィックス（`?prefix=`）

ほとんどのモデルは、プロバイダープレフィックス付きで公開されます。使用されるプレフィックスは、MODELS_CATALOG_PREFIX_MODE 機能フラグによって制御され、クエリパラメーターを使用してリクエストごとに上書きできます。これは、他のすべてのユーザーに適用されるサーバー全体の設定を変更せずに、クリーンな一覧を取得したいクライアントに便利です。

GET /v1/models?prefix=alias        # モデルごとに 1 つの ID — 短いエイリアスプレフィックス
GET /v1/models?prefix=dual         # 両方の形式（サーバーのデフォルト）
GET /v1/models?prefix=canonical    # 完全なプロバイダー ID プレフィックスのみ

モード	出力	注記
`dual`	`cc/claude-sonnet-4-6` および `claude/claude-sonnet-4-6`	デフォルト。両方の ID が同じモデルにルーティングされます。いずれかの形式をハードコードしたクライアント設定が引き続き動作するよう維持されています。カタログのサイズはおおよそ 2 倍になります。
`alias`	`cc/claude-sonnet-4-6`	モデルごとに 1 つのエントリ。個別のエイリアスがないプロバイダーも引き続きエントリを出力するため、何も失われません。
`canonical`	`claude/claude-sonnet-4-6`	完全なプロバイダー ID プレフィックスの下で、モデルごとに 1 つのエントリ。個別のエイリアスがないプロバイダー（例：`antigravity/…`、`agy/…`）も、ここで単一の ID を出力するため、何も失われません。

dual モードのミラーは、クエリパラメーターがなくても識別できます。プライマリ ID を指す parent フィールドが含まれています。

モデルピッカーを表示するクライアントは、?prefix=alias をリクエストする必要があります。OmniCopilot VS Code 拡張機能でもこの方法を使用しています。

思考なしモデルのバリアント

思考機能に対応した Claude モデルについては、/v1/models は ID の先頭に claude-3-omniroute-no-thinking/ が付いた思考なしバリアントも公開します。

claude-3-omniroute-no-thinking/<provider>/<model>

この ID を選択すると（たとえば、常に thinking ブロックを付加する Claude Code 設定内で）、推論を抑制した状態で実際の <provider>/<model> に解決されます。具体的には、/v1/messages パスでは thinking:{type:"disabled"} が設定され、/v1/chat/completions パスでは reasoning/reasoning_effort フィールドが削除されます。このバリアントは、思考をサポートし、かつ disabled を受け入れる Claude ファミリーのモデルに対してのみ一覧表示されます（そのため、たとえば disabled を拒否する adaptive-only モデルは除外されます）。運用者は、ModelSpec.noThinkingAlias を使用して、モデルごとにこのバリアントを強制的に有効または無効にできます。

プロバイダープラグインマニフェスト

GET /api/v1/provider-plugin-manifest

Bifrost、CLIProxyAPI、および将来のサイドカールーターで使用される、JSON セーフなプロバイダープラグインマニフェストを返します。レスポンスは TypeScript のプロバイダーレジストリから生成され、OAuth クライアントシークレット、実行時の環境解決、エグゼキューター関数、リクエストヘッダー、およびアカウントデータは意図的に除外されています。

サイドカーがプロセス外で実行され、open-sse/config/providerPluginManifestRegistry.ts を直接インポートできない場合は、このエンドポイントを使用してください。

互換性エンドポイント

メソッド	パス	形式
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	OpenAI Responses
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	OpenAI Images
POST	`/v1/images/edits`	OpenAI Images（編集／インペイント）
POST	`/v1/videos/generations`	OpenAI 形式の動画生成
POST	`/v1/music/generations`	OpenAI 形式の音楽生成
POST	`/v1/audio/transcriptions`	OpenAI Audio（STT）
POST	`/v1/audio/speech`	OpenAI TTS（音声本文を返す）
POST	`/v1/rerank`	Cohere/Voyage 形式の再ランキング
POST	`/v1/classify`	Jina 分類（`api.jina.ai`）
POST	`/v1/segment`	Jina セグメンター（`segment.jina.ai`）
POST	`/v1/moderations`	OpenAI Moderations
GET	`/v1/models`	OpenAI
POST	`/v1/messages/count_tokens`	Anthropic
GET	`/v1beta/models`	Gemini
POST	`/v1beta/models/{...path}`	Gemini generateContent
POST	`/v1/api/chat`	Ollama
GET	`/api/v1/vscode/{token}/`	OpenAI カタログエイリアス
GET	`/api/v1/vscode/{token}/models`	OpenAI モデルエイリアス
POST	`/api/v1/vscode/{token}/chat/completions`	OpenAI トークン付きエイリアス
POST	`/api/v1/vscode/{token}/responses`	OpenAI Responses トークン付きエイリアス
POST	`/api/v1/vscode/{token}/api/chat`	Ollama トークン付きエイリアス
GET	`/api/v1/vscode/{token}/api/tags`	Ollama タグのトークン付きエイリアス

すべての POST ルートは同じ形式に従います。Bearer your-api-key と、Zod で検証された JSON 本文（v1RerankSchema、v1ModerationSchema、v1AudioSpeechSchema など。src/shared/validation/schemas.ts を参照）を使用します。スキーマ検証に失敗すると 4xx が返されます。

Authorization: Bearer ... を付与できないクライアント向けに、OmniRoute は、クエリ文字列による互換方式（?token=...、?apiKey=...、?api_key=...、?key=...）または以下で説明する専用の /api/v1/vscode/{token}/... エンドポイントを介して、URL 内の API キーも受け付けます。

# 再ランキング
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina 分類（Foundation API 認証情報）
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina セグメンター
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina 検索（s.jina.ai、プロバイダーエイリアス：jina-search、jina-ai、jina）
POST /v1/search      { "query": "...", "provider": "jina-search" }

# モデレーション
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg（または指定された形式）の本文を返す
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# 画像編集（multipart）
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 動画／音楽生成（プロバイダー接頭辞付きモデル ID）
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

プロバイダー専用ルート

POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

プロバイダー接頭辞がない場合は、自動的に追加されます。モデルが一致しない場合は 400 が返されます。

Files API

バッチ入出力およびファイル用途別アップロードに対応する、OpenAI 互換のファイルエンドポイント。

メソッド	パス	説明
POST	`/v1/files`	ファイルをアップロード（マルチパート: `file`、`purpose`、`expires_after[anchor]`、`expires_after[seconds]`）— 最大 512 MiB
GET	`/v1/files`	認証済み API キーのファイルを一覧表示
GET	`/v1/files/[id]`	ファイルのメタデータを取得
DELETE	`/v1/files/[id]`	ファイルを削除
GET	`/v1/files/[id]/content`	未加工のファイル本体をストリーミングで返す

認証: Bearer API キー — ファイルのスコープは、getApiKeyRequestScope を介して API キーごとに設定されます。キーから表示、ダウンロード、削除できるのは、そのキーが所有するファイルのみです。キーを使用しないダッシュボードセッションはインスタンス全体を読み取れます。所有者のないファイル（匿名またはダッシュボードセッションによるアップロード）は、セッションを使用しないすべての呼び出し元に対してアクセスが拒否されます。GET /v1/files は、REQUIRE_API_KEY=false の場合でも、すべてのテナントのファイルを一覧表示する代わりに、匿名の呼び出し元、および解決できない提示済みキーに対して 401 を返します（GHSA-m3hp-hq9g-fpmv、GHSA-2jm2-mpx8-6523）。

Batches API

OpenAI 互換のバッチ処理。

メソッド	パス	説明
POST	`/v1/batches`	バッチを作成 — 本文は `v1BatchCreateSchema`（`input_file_id`、`endpoint`、`completion_window`）によって検証されます
GET	`/v1/batches`	バッチを一覧表示
GET	`/v1/batches/[id]`	バッチのステータスと `request_counts` を取得
DELETE	`/v1/batches/[id]`	完了または失敗したバッチを削除
POST	`/v1/batches/[id]/cancel`	進行中のバッチをキャンセル

認証: Bearer API キー。バッチのスコープは、ファイルと同じ 3 通りのルールに基づいて API キーごとに設定されます。アクセスできるのは自身のキーのみ、ダッシュボードセッションはインスタンス全体、所有者が null のレコードはセッションを使用しないすべての呼び出し元に対してアクセスが拒否されます（取得、削除、キャンセル、および作成時の input_file_id チェック）。 GET /v1/batches は、REQUIRE_API_KEY=false の場合でも、匿名の呼び出し元に対して 401 を返します。

Search API

Web/検索プロバイダーの抽象化レイヤー（Tavily、Brave、Exa、Serper など）。

メソッド	パス	説明
GET	`/v1/search`	設定済みの検索プロバイダーと機能を一覧表示
POST	`/v1/search`	検索クエリを実行 — リクエストボディは `v1SearchSchema` で検証され、キャッシュ/コアレッシングをサポート
GET	`/v1/search/analytics`	プロバイダーごとのヒット数/レイテンシ/キャッシュ統計

認証: Bearer APIキー（extractApiKey + isValidApiKey）。検索ポリシーは enforceApiKeyPolicy によって適用されます。

Web Fetch API

設定済みのWebフェッチプロバイダー（Firecrawl、Jina Reader、Tavily Extract、TinyFish Fetch、Nimble Extract）を使用して、URLからコンテンツを抽出します。

メソッド	パス	説明
POST	`/v1/web/fetch`	URLを取得/スクレイピング — リクエストボディは `v1WebFetchSchema` で検証されます

認証: Bearer APIキー（extractApiKey + isValidApiKey）。ポリシーは enforceApiKeyPolicy によって適用されます。

クォータを考慮したフォールバック（#8297）: 明示的な provider が指定されていない場合、プール（firecrawl → jina-reader → tavily-search → tinyfish → nimble-search）は、固定された優先順位（fill-first）で走査されます。レート制限中であっても設定済みのプロバイダーは、リクエストをそこで終了させる代わりにスキップされます。また、再試行可能な障害またはクォータに起因するアップストリーム障害（HTTP 429 は常に対象。Firecrawl/Tavily/TinyFish のクォータ方式の無料枠では 402/403 も対象 — Jina Reader では対象外であり、通常の 400 bad request は一切対象外）は、リクエスト時に、まだ試行されていない認証情報設定済みの次のプロバイダーへフォールスルーします。プール内のすべてのプロバイダーを使い果たした場合、エンドポイントは従来の汎用的な 400 の代わりに、単一の 429（Retry-After ヘッダー付き）を返します。明示的な provider が要求された場合、サイレントフォールバックは 行われません。レート制限中または失敗した明示的なプロバイダーは、それ自身のエラーを返します（レート制限中は 429、それ以外はアップストリームのステータス）。

WebSocketストリーミング

GET /v1/ws?handshake=1

WebSocketアップグレードのハンドシェイクを検証し、ワイヤープロトコルのメッセージ例（request、cancel）を返します。実際のWSフレームは、Next.jsのルートテーブル外にある同梱のWSサーバーによって処理されます。

認証: ハンドシェイク時のBearer APIキー。

WebSocket経由のResponses API（codexのみ）

# HTTP APIと同じhost:port（デフォルトは20128）を使用し、接続をアップグレードします:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# （または: -H "Authorization: Bearer <OMNIROUTE_API_KEY>"）

# 最初のフレームは必ずresponse.createでなければなりません:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API-over-WebSocketプロキシは、codex 専用（ChatGPT バックエンド）として接続されています。API/ダッシュボードと同じポートで、パス /v1/responses、 /responses、/api/v1/responses をリッスンします。最初の response.create フレームで、内部の codex-responses-ws ブリッジを介して認証と準備を行い、codex OAuth接続を選択し、wreq-js トランスポート経由で wss://chatgpt.com/backend-api/codex/responses へトンネリングします。codex以外のモデルは拒否されます（codex_ws_provider_required）。クォータ共有ルーティングには model: "qtSd/<group>/codex/<model>" を使用してください。実装は app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts にあります。

認証: ハンドシェイク時のBearer APIキー。同梱のHTTPサーバー（server-ws.mjs）が有効なエントリーポイントである必要があります（app/server-ws.mjs が存在する場合、デフォルトで有効です）。

モデルID: `codex/` プレフィックスなしのChatGPT IDを使用

OpenAI Codex CLI は、supports_websockets = true の場合にクライアント側でモデル名を検証し、codex/gpt-5.5 のような プロバイダープレフィックス付きIDを拒否します（The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account）。プレフィックスなしのID（例: gpt-5.5）を送信してください。OmniRouteのブリッジは codex専用であるため、アップストリームへトンネリングする前に、プレフィックスなしのIDをcodexモデルとして再解決します（resolveCodexWsModelInfo）。これは、プレフィックスなしの gpt-5.5 がHTTP経由では本来別のプロバイダーにルーティングされる場合でも同様です。

OpenAI Codex CLIの設定

WebSocketをサポートするカスタムプロバイダーを ~/.codex/config.toml に追加して、 Codex CLIの接続先をOmniRouteに設定します（既存の設定に影響を与えないよう、別の CODEX_HOME を使用してください）。

model = "gpt-5.5"                 # プレフィックスなしのID — "codex/gpt-5.5"ではありません
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # 末尾にスラッシュを付けません。WS URLはここから導出されます（本番環境ではhttps/wssを使用してください）
wire_api = "responses"                    # 2026年2月以降でサポートされる唯一の値
supports_websockets = true                # Responses-over-WSトランスポートを有効にします
env_key = "OMNIROUTE_API_KEY"             # OmniRoute APIキー（Bearer）を保持します

export OMNIROUTE_API_KEY=sk-...           # OmniRoute APIキー（REQUIRE_API_KEY=falseの場合は任意のキー）
codex exec "Responda apenas: PONG"

CLIは base_url + /responses をWebSocketへアップグレードし、OmniRouteは選択された codex OAuth接続へトンネリングします。ローカルサーバーに対してエンドツーエンドで検証済みです。ChatGPTは codex.rate_limits + response.created を返し、完了結果をストリーミングします。

クォータと問題の報告

メソッド	パス	説明
GET	`/v1/quotas/check`	登録済みキーを発行する前に、`provider` + `accountId` のクォータを事前検証します
POST	`/v1/issues/report`	クォータまたはキー発行の失敗を GitHub に報告します（`GITHUB_ISSUES_REPO` + トークンが必要）

認証: Bearer API キー（isAuthenticated）。

セルフサービスでの使用状況確認（`/api/usage/om-usage`）

どの API キーでも、管理者認証なしで 自身の 使用状況とクォータを確認できます。これは、クライアント（CLI、OmniCopilot パネル）がキーホルダーに利用額を表示するために使用するエンドポイントです。

# テキスト形式（従来の仕様 — ターミナル向けのプレーンテキスト）
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# 構造化形式 — UI が使用する形式
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

キーでは allowUsageCommand が有効になっている必要があります（デフォルトでは無効です。ダッシュボードの API キーマネージャーでキーごとに切り替えます）。有効でない場合、エンドポイントは 403 を返します。

?format=json は判別可能な形式を返すため、呼び出し元が拒否レスポンスからデータフィールドを読み取ることはありません。成功時:

{
  "allowed": true,
  // キーでキー単位の使用上限（1 日あたり／1 週間あたりの USD）を有効にした場合にのみ存在:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 選択されたプロバイダーのクォータスナップショット。まだ何もキャッシュされていない場合は null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // 各接続のスナップショット。UI で複数のプロバイダーを並べて表示可能:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

拒否時（不正なキーの場合は 401／許可されていない場合は 403）、同じルートが { "allowed": false, "error": { "message": "…" } } を返します。存在するものの空の personal/provider （キーは許可されているが、まだ情報を取得していない状態）は拒否とは異なる状態であり、これらを区別できるのは JSON 形式のみです。

認証: 呼び出し元自身の Bearer API キー。isValidApiKey で検証されます。これは管理インターフェース（/api/keys/…）ではなく、管理インターフェースは引き続き requireManagementAuth で保護されます。

セマンティックキャッシュ

# キャッシュ統計を取得
GET /api/cache/stats

# すべてのキャッシュをクリア
DELETE /api/cache/stats

レスポンス例:

{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}

レイテンシへの影響

セマンティックキャッシュが HIT した場合、アップストリーム呼び出しなしで キャッシュからレスポンスが返されるため、報告される X-OmniRoute-Response-Latency は（元のアップストリームレイテンシに関係なく）ほぼゼロになります。レイテンシを重視するクライアント（ベンチマーク、p50/p99 モニタリング）は、X-OmniRoute-Cache-Latency レスポンスヘッダーを確認する必要があります。

値	意味
`synthetic`	キャッシュから返されたレスポンス。レイテンシは実際のアップストリーム時間ではありません
(なし)	実際のアップストリーム呼び出しからのレスポンス

キー単位のキャッシュバイパス

API キーでは、cacheDefaultMode を使用してセマンティックキャッシュの読み取りを無効にできます。

値	動作
`legacy`	通常のキャッシュ動作（デフォルト）
`bypass`	キャッシュ検索を完全にスキップし、常にアップストリームを呼び出します

キーの作成時（POST /api/keys）に設定するか、更新時（PATCH /api/keys/[id]）に変更します。

{ "cacheDefaultMode": "bypass" }

リクエスト単位のバイパス

キーの設定に関係なく、任意のリクエストでキャッシュをバイパスできます。

X-OmniRoute-No-Cache: true

ダッシュボードと管理

管理ルート（公開の認証/ログインを除く /api/*）は、通常の推論 API キーでは認可されません。認証情報の種類、スコープ、curl の例については、以下を参照してください：管理認証。

認証

エンドポイント	メソッド	説明
`/api/auth/login`	POST	ログイン
`/api/auth/logout`	POST	ログアウト
`/api/settings/require-login`	GET/PUT	ログイン必須設定の切り替え

プロバイダー管理

エンドポイント	メソッド	説明
`/api/providers`	GET/POST	プロバイダーの一覧表示 / 作成
`/api/providers/[id]`	GET/PUT/DELETE	プロバイダーの管理
`/api/providers/[id]/test`	POST	プロバイダー接続のテスト
`/api/providers/[id]/models`	GET	プロバイダーモデルの一覧表示
`/api/providers/validate`	POST	プロバイダー設定の検証
`/api/providers/bulk`	POST	1 つのプロバイダーに API キーを一括追加
`/api/providers/import`	POST	解析済みの CSV/JSON ファイルから異種プロバイダーのリストをインポート（#6836）。行ごとの部分的な失敗結果を返す
`/api/provider-nodes*`	各種	プロバイダーノードの管理
`/api/provider-models`	GET/POST/PATCH/DELETE	カスタムモデル（追加、更新、非表示/表示、削除）

OAuth フロー

エンドポイント	メソッド	説明
`/api/oauth/[provider]/[action]`	各種	プロバイダー固有の OAuth

ルーティングと設定

エンドポイント	メソッド	説明
`/api/models/alias`	GET/POST	モデルエイリアス
`/api/models/catalog`	GET	プロバイダーおよびタイプ別の全モデル
`/api/combos*`	各種	コンボ管理
`/api/keys*`	各種	API キー管理
`/api/pricing`	GET	モデルの価格設定

使用状況と分析

エンドポイント	メソッド	説明
`/api/usage/history`	GET	使用履歴
`/api/usage/logs`	GET	使用ログ
`/api/usage/request-logs`	GET	リクエスト単位のログ
`/api/usage/[connectionId]`	GET	接続ごとの使用状況
`/api/usage/token-limits`	GET/POST/DELETE	APIキーごとのトークン上限予算
`/api/usage/model-latency-stats`	GET	プロバイダー／モデルごとのローリングレイテンシ集計（平均値／p50／p95／p99、成功率）。フィルター：`windowHours`／`minSamples`／`maxRows`／`provider`／`model`（#6873）
`/api/usage/cache-health`	GET	`call_logs` に基づくプロンプトキャッシュの健全性サマリー — 書き込み／読み取り比率、書き込みサイズ分布のp50／p90／p99、大量書き込みの集中度、モデルごとの内訳、および `healthy`／`degraded`／`thrash`／`no-data` の判定。クエリパラメーターは `range`（`1h`\|`24h`\|`7d`\|`30d`、デフォルトは `24h`）と、任意の `model`（#8827）

設定

エンドポイント	メソッド	説明
`/api/settings`	GET/PUT/PATCH	一般設定
`/api/settings/proxy`	GET/PUT	ネットワークプロキシ設定
`/api/settings/proxy/test`	POST	プロキシ接続をテスト
`/api/settings/ip-filter`	GET/PUT	IP許可リスト／ブロックリスト
`/api/settings/thinking-budget`	GET/PUT	思考／推論リクエストの書き換えモード（パススルー／自動削除／カスタム／適応型）。圧縮とは独立しています。THINKING_BUDGET.md を参照してください。
`/api/settings/system-prompt`	GET/PUT	グローバルシステムプロンプト
`/api/settings/compression`	GET/PUT	グローバル圧縮設定
`/api/settings/purge-request-history`	POST	リクエストログの行とローカルの呼び出しログアーティファクトを消去

コンテキストと圧縮

エンドポイント	メソッド	説明
`/api/compression/preview`	POST	off/lite/standard/aggressive/ultra/RTK/stacked 圧縮をプレビュー
`/api/compression/language-packs`	GET	利用可能な Caveman 言語パックを一覧表示
`/api/compression/rules`	GET	Caveman ルールのメタデータを一覧表示
`/api/context/caveman/config`	GET/PUT	Caveman 固有設定のエイリアス
`/api/context/rtk/config`	GET/PUT	カスタムフィルターと生出力の保持を含む、RTK 固有の設定
`/api/context/rtk/filters`	GET	RTK フィルターカタログとカスタムフィルターの診断
`/api/context/rtk/test`	POST	テキストペイロードに対して RTK のプレビュー／テストを実行
`/api/context/rtk/raw-output/[id]`	GET	ポインター ID を使用して、保持された編集済み生出力を読み取り
`/api/context/combos`	GET/POST	圧縮コンボの一覧表示／作成
`/api/context/combos/[id]`	GET/PUT/DELETE	圧縮コンボの詳細表示／更新／削除
`/api/context/combos/[id]/assignments`	GET/PUT	圧縮コンボをルーティングコンボに割り当て
`/api/context/analytics`	GET	圧縮分析のエイリアス

監視

エンドポイント	メソッド	説明
`/api/sessions`	GET	アクティブなセッションの追跡
`/api/rate-limits`	GET	アカウントごとのレート制限
`/api/monitoring/health`	GET	ヘルスチェックとプロバイダーの概要（`catalogCount`、`configuredCount`、`activeCount`、`monitoredCount`）。管理ビューには `credentialHealth` が含まれます。内容は、プローブキャッシュのスカラー値、`failed>0` の場合の `failedConnections`、および `staleDbNonOkCount`（ゲージではなく SQLite の固定 `test_status`）です。MONITORING_GUIDE.mdを参照してください。
`/api/cache/stats`	GET/DELETE	キャッシュの統計／クリア
`/api/modality-bridge/stats`	GET	メモリ内の `attempts`、成功数／`bridged`、失敗数、キャッシュヒット数、`totalLatencyMs`、`latencySamples`、サンプル数を分母とする `averageLatencyMs`、および最終使用時刻（再起動時にリセット、管理認証が必要）
`/api/modality-bridge/video/runtime`	GET	管理認証／プローブの前に厳格な信頼済みループバックチェックを実施。サニタイズされた FFmpeg/ffprobe の可用性とバージョンを返します（no-store）
`/api/modality-bridge/video/extract`	POST	内部向けの認証済み信頼済みループバック用バイトブローカー。入力上限は 50 MiB、キューは制限付き、出力上限は 32 MiB、容量超過時は `503`、切断時は `499`、期限超過時は `504`。公開アップロード API ではありません

バックアップとエクスポート／インポート

エンドポイント	メソッド	説明
`/api/db-backups`	GET	利用可能なバックアップを一覧表示
`/api/db-backups`	PUT	手動バックアップを作成
`/api/db-backups`	POST	指定したバックアップから復元
`/api/db-backups/export`	GET	データベースを .sqlite ファイルとしてダウンロード
`/api/db-backups/import`	POST	.sqlite ファイルをアップロードしてデータベースを置換
`/api/db-backups/exportAll`	GET	完全なバックアップを .tar.gz アーカイブとしてダウンロード

クラウド同期

エンドポイント	メソッド	説明
`/api/sync/cloud`	各種	クラウド同期操作
`/api/sync/initialize`	POST	同期を初期化
`/api/cloud/*`	各種	クラウド管理

トンネル

エンドポイント	メソッド	説明
`/api/tunnels/cloudflared`	GET	ダッシュボード向けに Cloudflare Quick Tunnel のインストール／実行状況を取得
`/api/tunnels/cloudflared`	POST	Cloudflare Quick Tunnel を有効化または無効化（`action=enable/disable`）
`/api/tunnels/ngrok`	GET	ダッシュボード向けに ngrok Tunnel の実行状況を取得
`/api/tunnels/ngrok`	POST	ngrok Tunnel を有効化または無効化（`action=enable/disable`）

CLI ツール

エンドポイント	メソッド	説明
`/api/cli-tools/claude-settings`	GET	Claude CLI の状態
`/api/cli-tools/codex-settings`	GET	Codex CLI の状態
`/api/cli-tools/droid-settings`	GET	Droid CLI の状態
`/api/cli-tools/openclaw-settings`	GET	OpenClaw CLI の状態
`/api/cli-tools/runtime/[toolId]`	GET	汎用 CLI ランタイム

CLI のレスポンスには、installed、runnable、command、commandPath、runtimeMode、reason が含まれます。

ACP エージェント

エンドポイント	メソッド	説明
`/api/acp/agents`	GET	検出されたすべてのエージェント（組み込み + カスタム）を状態とともに一覧表示
`/api/acp/agents`	POST	カスタムエージェントを追加、または検出キャッシュを更新
`/api/acp/agents`	DELETE	`id` クエリパラメーターで指定したカスタムエージェントを削除

GET レスポンスには、agents[]（id、name、binary、version、installed、protocol、isCustom）および summary（total、installed、notFound、builtIn、custom）が含まれます。

耐障害性とレート制限

エンドポイント	メソッド	説明
`/api/resilience`	GET/PATCH	リクエストキュー、接続クールダウン、プロバイダーブレーカー、および待機設定を取得／更新
`/api/resilience/reset`	POST	プロバイダーのサーキットブレーカーをリセット
`/api/resilience/model-cooldowns`	GET	有効な（プロバイダー、接続、モデル）単位のロックアウトを残り時間順で一覧表示
`/api/resilience/model-cooldowns`	DELETE	モデルのロックアウトを解除 — 本文に `{provider, model}`、またはすべて削除する場合は `{all: true}` を指定
`/api/rate-limits`	GET	アカウントごとのレート制限状態
`/api/rate-limit`	GET	グローバルなレート制限設定

4 つの /api/resilience/* ルートはすべて 管理認証（requireManagementAuth）を必要とします。プロバイダーブレーカー、接続クールダウン、モデルロックアウトの詳しい違いについては、耐障害性（詳細）を参照してください。

評価

エンドポイント	メソッド	説明
`/api/evals`	GET/POST	評価スイートを一覧表示／評価を実行

ポリシー

エンドポイント	メソッド	説明
`/api/policies`	GET/POST/DELETE	ルーティングポリシーを管理

コンプライアンス

エンドポイント	メソッド	説明
`/api/compliance/audit-log`	GET	コンプライアンス監査ログ（直近 N 件）

v1beta（Gemini 互換）

エンドポイント	メソッド	説明
`/v1beta/models`	GET	Gemini 形式でモデルを一覧表示
`/v1beta/models/{...path}`	POST	Gemini の `generateContent` エンドポイント

これらのエンドポイントは、ネイティブな Gemini SDK との互換性を必要とするクライアント向けに、Gemini の API 形式を再現しています。

内部／システム API

エンドポイント	メソッド	説明
`/api/init`	GET	アプリケーションの初期化チェック（初回実行時に使用）
`/api/tags`	GET	Ollama 互換のモデルタグ（Ollama クライアント用）
`/api/restart`	POST	サーバーの正常な再起動を開始
`/api/shutdown`	POST	サーバーの正常なシャットダウンを開始
`/api/system/env/repair`	POST	OAuth プロバイダーの環境変数を修復

注: これらのエンドポイントは、システム内部または Ollama クライアントとの互換性のために使用されます。通常、エンドユーザーが呼び出すことはありません。

OAuth 環境の修復 (v3.6.1+)

POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}

特定のプロバイダーについて、欠落または破損した OAuth 環境変数を修復します。以下を返します。

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

音声文字起こし

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

設定済みの任意の STT プロバイダーを使用して、音声ファイルを文字起こしします。最初のパスセグメントでネイティブプロバイダー（openai/…、deepgram/…）を選択します。別ベンダーのモデルを再公開するゲートウェイでは、修飾された ID （openrouter/deepgram/nova-3）を使用します。

リクエスト:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

レスポンス:

{
  "text": "こんにちは。これは文字起こしされた音声コンテンツです。",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

モデル ID の例: openai/whisper-1（OpenAI キーが必要）、 openrouter/deepgram/nova-3（OpenRouter キーが必要）、 deepgram/nova-3（ネイティブの Deepgram キーが必要）。修飾されていない deepgram/nova-3 リクエストでは、OpenRouter は使用されません。

対応形式: mp3、wav、m4a、flac、ogg、webm。

Ollama 互換性

Ollama の API 形式を使用するクライアント向け:

# チャットエンドポイント（Ollama 形式）
POST /v1/api/chat

# モデル一覧（Ollama 形式）
GET /api/tags

リクエストは、Ollama 形式と内部形式の間で自動的に変換されます。

トークン付き VS Code / ヘッダーなしエイリアス

インテグレーションで Authorization ヘッダーを挿入できず、API キーをベース URL に埋め込む必要がある場合は、これらのエイリアスを使用してください。

# OpenAI 形式のカタログエイリアス
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI 形式のチャットエイリアス
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama 形式のエイリアス
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

例:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

注意:

トークン付きエイリアスは /v1/* および /api/tags と同じハンドラーを再利用するため、レスポンス形式は同一です。
クライアントがカスタムヘッダーをサポートしている場合は、可能な限り Authorization: Bearer ... を使用してください。
URL ベースのトークンは、リバースプロキシのログ、ブラウザー履歴、および OmniRoute 外部のテレメトリに記録される可能性があります。デフォルトの認証方式ではなく、互換性のためのオプションとして扱ってください。

テレメトリ

# レイテンシーテレメトリの概要を取得（プロバイダーごとの p50/p95/p99）
GET /api/telemetry/summary

レスポンス:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

予算

# すべての API キーの予算状況を取得
GET /api/usage/budget

# 予算を設定または更新
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

スキーマに関する注意事項（setBudgetSchema）: apiKeyId は必須です。dailyLimitUsd、weeklyLimitUsd、monthlyLimitUsd のうち少なくとも 1 つはゼロより大きい値でなければなりません。オプションフィールド: warningThreshold（0～1）、resetInterval（daily | weekly | monthly）、resetTime（HH:MM）。従来の {keyId, limit, period} 形式を使用すると、400 Bad Request が返されます。

トークン制限

API キーごとの トークン 予算（上記の USD ベースの予算とは別）。リクエストパス上でインラインに適用されます。キーの現在のウィンドウ使用量が上限に達すると、リクエストは 429 Too Many Requests で拒否されます。制限は、特定の model、provider にスコープ設定することも、キー全体に global に適用することもできます。複数の制限がリクエストに一致する場合は、最も厳しい制限が優先されます。

# キーのトークン制限を一覧表示（現在のウィンドウ使用量を含む）
GET /api/usage/token-limits?apiKeyId=key-123

# トークン制限を作成または更新
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# ID を指定してトークン制限を削除
DELETE /api/usage/token-limits?id=tl-abc

スキーマに関する注記（setTokenLimitSchema）：apiKeyId と scopeType（model | provider | global）は必須です。scopeType が global でない限り、scopeValue は必須です（例：model スコープではモデル ID、provider スコープではプロバイダー ID）。tokenLimit は正の整数である必要があります（文字列から変換されます）。任意項目：id（作成時は省略し、更新時は指定）、resetInterval（daily | weekly | monthly、デフォルトは monthly）、resetTime（HH:MM）、enabled（デフォルトは true）。GET レスポンスでは、各制限に tokensUsed、remaining、windowStart、periodStartAt、nextResetAt が追加されます。これは管理クラスのエンドポイントです（認証は authz パイプラインによって一元的に適用されます）。

リクエスト処理

クライアントが /v1/* にリクエストを送信
ルートハンドラーが handleChat、handleEmbedding、handleAudioTranscription、または handleImageGeneration を呼び出す
モデルを解決（プロバイダー/モデルの直接指定、またはエイリアス/コンボ）
アカウントの可用性をフィルタリングし、ローカル DB から認証情報を選択
チャットの場合：handleChatCore がセマンティック/シグネチャキャッシュを確認し、コンボの圧縮設定を解決
有効な場合、プロバイダー向け変換の前にプロアクティブ圧縮を実行（lite、Caveman、RTK、またはそれらのスタック）
プロバイダーエグゼキューターがアップストリームリクエストを送信
レスポンスをクライアント形式に再変換（チャット）するか、そのまま返却（埋め込み/画像/音声）
使用量、圧縮分析、リクエストログを記録
エラー発生時、コンボルールに従ってフォールバックを適用

アーキテクチャの完全なリファレンス：ARCHITECTURE.md

コンボ管理

上位レベルのルーティングコンボ（/api/combos* で概要を説明済み）は、モデル ID パターンから 1:1 でマッピングすることもでき、OpenAI 形式のモデル ID をコンボへ透過的にリダイレクトできます。

メソッド	パス	説明
GET	`/api/model-combo-mappings`	すべてのモデル→コンボマッピングを一覧表示
POST	`/api/model-combo-mappings`	マッピングを作成 — 本文：`{pattern, comboId, priority?, enabled?, description?}`
GET	`/api/model-combo-mappings/[id]`	単一のマッピングを取得
PUT	`/api/model-combo-mappings/[id]`	既存のマッピングのフィールドを更新
DELETE	`/api/model-combo-mappings/[id]`	マッピングを削除

認証： 管理セッション/API キー（requireManagementAuth）。

Webhook

OmniRoute イベント（リクエスト完了、クォータ枯渇、キーのローテーションなど）に対する送信 Webhook サブスクリプション。

メソッド	パス	説明
GET	`/api/webhooks`	Webhook の一覧を取得（シークレットは `<prefix>...` にマスクされます）
POST	`/api/webhooks`	Webhook を作成 — ボディ: `{url, events?: ["*"], secret?, description?}`
GET	`/api/webhooks/[id]`	Webhook を取得
PUT	`/api/webhooks/[id]`	url/events/secret/description を更新
DELETE	`/api/webhooks/[id]`	Webhook を削除
POST	`/api/webhooks/[id]/test`	Webhook URL にテストペイロードを送信し、配信ステータスを返す

認証: 管理セッション/API キー（requireManagementAuth）。

登録済みキー（自動管理）

自動キー管理サブシステムが、基盤となるプロバイダー/アカウントに対して、日次/時間単位のクォータ付き API キーを発行およびローテーションするために使用します。

メソッド	パス	説明
GET	`/api/v1/registered-keys`	登録済みキーの一覧を取得（マスクされたプレフィックスのみ）
POST	`/api/v1/registered-keys`	新しい登録済みキーを発行 — ボディ: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`。生のキーは一度だけ返されます。クォータにより拒否された場合は `429` を返します。
GET	`/api/v1/registered-keys/[id]`	登録済みキーのメタデータを取得（生のキー情報は含まれません）
DELETE	`/api/v1/registered-keys/[id]`	登録済みキーを失効
POST	`/api/v1/registered-keys/[id]/revoke`	明示的な失効エンドポイント（DELETE と同じ効果）

認証: Bearer API キー（isAuthenticated）。/v1/quotas/check および /v1/issues/report も参照してください。

エージェントプロトコル

OmniRoute ユーザーに代わってリモートで実行されるクラウドエージェントタスク（Claude Code、Codex Cloud、OpenHands など）。

メソッド	パス	説明
GET	`/api/v1/agents/tasks`	タスクを一覧表示 — 任意の `?provider=`、`?status=`、`?limit=`（1～500、デフォルトは 50）
POST	`/api/v1/agents/tasks`	タスクを作成 — リクエストボディは `CreateCloudAgentTaskSchema`（`providerId`、`prompt`、`source`、`options?`）で検証されます。タスクエンベロープとともに `201` を返します
DELETE	`/api/v1/agents/tasks?id=...`	タスクを削除
GET	`/api/v1/agents/tasks/[id]`	タスクを読み取り — `external_id` が設定されている場合、上流のクラウドエージェントからステータスを同期的に更新します
POST	`/api/v1/agents/tasks/[id]`	判別可能なアクション：`{action: "approve"}`、`{action: "message", message}`、または `{action: "cancel"}`
DELETE	`/api/v1/agents/tasks/[id]`	id で指定されたタスクを削除

認証： すべてのメソッドで管理認証（requireCloudAgentManagementAuth）が必要です。v3.8.0 より前は認証不要でした。破壊的変更についてはコミット 588a0333 を参照してください。

# Claude Code のクラウドタスクを作成
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

管理プロキシ

プロバイダー、アカウント、またはグローバルに割り当て可能な送信 HTTP(S)/SOCKS プロキシ。

メソッド	パス	説明
GET	`/api/v1/management/proxies`	プロキシを一覧表示（`?id=` を指定すると 1 件を返し、`?id=&where_used=1` を指定すると割り当てグラフを返します）
POST	`/api/v1/management/proxies`	プロキシを作成 — リクエストボディは `createProxyRegistrySchema` で検証されます
PATCH	`/api/v1/management/proxies`	プロキシを更新 — リクエストボディは `updateProxyRegistrySchema` で検証されます（`id` が必要）
DELETE	`/api/v1/management/proxies?id=...&force=1`	プロキシを削除（割り当てを解除するには `force=1` を使用）
GET	`/api/v1/management/proxies/assignments`	割り当てを一覧表示 — `proxy_id`、`scope`、`scope_id` でフィルタリング可能。接続に対するアクティブなプロキシを解決するには `resolve_connection_id=<id>` を指定します
PUT	`/api/v1/management/proxies/assignments`	割り当て — リクエストボディは `proxyAssignmentSchema`（`{scope, scopeId?, proxyId?}`）で検証されます。ディスパッチャーキャッシュをクリアします
PUT	`/api/v1/management/proxies/bulk-assign`	一括割り当て — リクエストボディは `bulkProxyAssignmentSchema`（`{scope, scopeIds[], proxyId?}`）で検証されます
GET	`/api/v1/management/proxies/health?hours=24`	指定期間内のプロキシの稼働状態（成功数／失敗数、レイテンシ）を集計します

認証： すべてのルートで管理セッション/API キー（requireManagementAuth）が必要です。

タスク説明にある POST /api/v1/management/proxies/[id]/assignments および POST /api/v1/management/proxies/[id]/health は、上記のフラットな /assignments および /health ルートによって提供されます。コードベースに ID ごとのサブルートはありません。

レジリエンス（拡張）

OmniRoute は、互いに独立した 3 つの一時的障害メカニズムを提供します。以下の管理エンドポイントを使用して、運用担当者はそれらの状態を確認および上書きできます。

スコープ	状態の保存先	参照	リセット / クリア
プロバイダーブレーカー	`domain_circuit_breakers` + インメモリ	`/api/monitoring/health`	`POST /api/resilience/reset`
接続クールダウン	プロバイダー接続の `rateLimitedUntil`	`/api/rate-limits`, `/api/providers/[id]`	（遅延方式で再有効化。プロバイダーの PUT でクリア）
モデルロックアウト	インメモリのモデル可用性レジストリ	`GET /api/resilience/model-cooldowns`	`DELETE /api/resilience/model-cooldowns`

PATCH /api/resilience は、providerBreaker.oauth および providerBreaker.apikey でプロバイダーブレーカーのオーバーライドを受け付けます。各プロファイルは degradationThreshold、failureThreshold、resetTimeoutMs をサポートします。同じフィールドは「Dashboard → Settings → Resilience」にも表示されます。

# 単一モデルのロックアウトをクリア
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# すべてのロックアウトを削除
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

概念の完全なリファレンスおよびブレーカーのデフォルト値については、CLAUDE.md →「レジリエンスのランタイム状態」を参照してください。

スキル

カスタム実行可能ハンドラーを使用して OmniRoute を拡張するためのスキルフレームワークと、マーケットプレイス連携です。

メソッド	パス	説明
GET	`/api/skills`	インストール済みのスキルを一覧表示 — `?q=`、`?mode=on\|off\|auto`、`?source=skillsmp\|skillssh\|local` で絞り込み可能、ページネーション対応
GET	`/api/skills/[id]`	1 つのスキルを取得
PUT	`/api/skills/[id]`	スキルを更新（名前、説明、モード、スキーマ、ハンドラー、タグ）
DELETE	`/api/skills/[id]`	スキルをアンインストール
POST	`/api/skills/install`	未加工のマニフェストからスキルをインストール — 本文: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`
GET	`/api/skills/executions`	最近のスキル実行を一覧表示（入力、出力、実行時間を含む監査証跡）
GET	`/api/skills/marketplace?q=...`	SkillsMP マーケットプレイスから検索結果または人気スキル一覧を取得（`skillsmpApiKey` 設定が必要）
POST	`/api/skills/marketplace/install`	SkillsMP から ID を指定してスキルをインストール
GET	`/api/skills/skillssh?q=&limit=`	skills.sh レジストリを検索
POST	`/api/skills/skillssh/install`	skills.sh から ID を指定してスキルをインストール

認証: 管理セッション/API キー。マーケットプレイス検索ルートでは、管理認証または Bearer API キー（isAuthenticated）のいずれかを使用できます。

メモリ

API キー／セッション単位でスコープ設定された、永続的な会話／事実メモリストア。

メソッド	パス	説明
GET	`/api/memory`	メモリ一覧 — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`、および `offset/limit` または `page/limit` によるページネーション
POST	`/api/memory`	メモリを作成 — Zod によって検証される本文: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`
GET	`/api/memory/[id]`	単一のメモリを取得
DELETE	`/api/memory/[id]`	メモリを削除
GET	`/api/memory/health`	メモリサブシステムの健全性（DB 接続、埋め込みバックエンド、ベクトルインデックスの状態）

認証: 管理セッション／API キー（requireManagementAuth）。type の列挙値: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL（src/lib/memory/types.ts の MemoryType を参照）。

MCP サーバー

OmniRoute には、3 つのトランスポート（stdio、SSE、streamable-http）とスコープ付きツールを備えた Model Context Protocol サーバーが組み込まれています。以下のダッシュボードエンドポイントは、ステータス／監査データを読み取り、HTTP トランスポートをプロキシします。

メソッド	パス	説明
GET	`/api/mcp/status`	ハートビート、トランスポート、オンライン状態、最終呼び出し、上位ツール、24 時間の成功率
GET	`/api/mcp/tools`	`name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` を含む MCP ツール一覧
GET	`/api/mcp/sse`	SSE トランスポート用の SSE ストリームを開く（MCP が無効、またはトランスポートが一致しない場合は `503` を返す）
POST	`/api/mcp/sse`	SSE トランスポートで JSON-RPC フレームを送信
GET	`/api/mcp/stream`	Streamable HTTP トランスポートの SSE 側を開く（サーバー起点のメッセージ）
POST	`/api/mcp/stream`	Streamable HTTP トランスポートで JSON-RPC フレームを送信
DELETE	`/api/mcp/stream`	Streamable HTTP セッションを終了
GET	`/api/mcp/audit`	監査ログを照会 — `?limit=`, `?offset=`, `?tool=`, `?success=true	false`,` ?apiKeyId=`
GET	`/api/mcp/audit/stats`	監査統計を集計（合計、成功率、平均所要時間、上位ツール）

認証: sse／stream トランスポートは MCP 固有の認証方式（mcp スコープを持つ Bearer API キー）に従います。status／tools／audit* ルートはダッシュボードから読み取り可能です（ダッシュボードホストへのアクセスに必要な認証以外に、追加の認証は不要です）。

どちらの HTTP トランスポートも settings.mcpEnabled と settings.mcpTransport によって制御されます。トランスポートが一致しない場合は 400、MCP が無効な場合は 503 が返されます。

A2A サーバー

OmniRoute は、A2A（Agent-to-Agent）JSON-RPC 2.0 エンドポイントに加え、確認やダッシュボードで使用するための REST ラッパーを公開します。

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # OMNIROUTE_API_KEY が設定されていない場合は省略可能
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

サポートされるメソッド（すべて settings.a2aEnabled によって制御されます）：

メソッド	説明
`message/send`	スキルを同期実行し、`{task, artifacts, metadata}` を返します
`message/stream`	同じスキルセットをストリーミング SSE で実行します
`tasks/get`	`taskId` を指定してタスクを取得します
`tasks/cancel`	`taskId` を指定してタスクをキャンセルします

組み込みスキル：smart-routing、quota-management、provider-discovery、cost-analysis、health-report。

エージェントカード

GET /.well-known/agent.json

公開 A2A エージェントカード（名前、説明、機能、スキルカタログ、認証スキーム）を返します。公開キャッシュの有効期間は 1 時間です。認証は不要です。

REST ヘルパー

メソッド	パス	説明
GET	`/api/a2a/status`	A2A の有効状態、タスク統計、キャッシュされたエージェントカードの概要
GET	`/api/a2a/tasks`	タスク一覧 — `?state=submitted\|working\|completed\|failed\|cancelled`、`?skill=`、`?limit=`（≤200）、`?offset=`
POST	`/api/a2a/tasks`	（REST ヘルパーとしては未実装 — JSON-RPC の `message/send` を使用して作成）
GET	`/api/a2a/tasks/[id]`	1 件のタスクを取得
POST	`/api/a2a/tasks/[id]/cancel`	タスクをキャンセル

認証： REST ヘルパーは管理認証なしで動作し、ダッシュボードから参照できます。JSON-RPC の /a2a ルートは、設定されている場合に Bearer OMNIROUTE_API_KEY を使用します。

クラウド、評価、アセスメント

メソッド	パス	説明
POST	`/api/cloud/auth`	Bearer キーを検証し、マスクされたプロバイダー接続とモデルエイリアスをクラウド同期クライアント向けに返します
POST	`/api/cloud/credentials/update`	クラウド同期されたプロバイダーの暗号化済み認証情報を更新します
POST	`/api/cloud/model/resolve`	ローカルルーティングテーブルを使用して、論理モデル ID を具体的なプロバイダー／モデルに解決します
GET	`/api/cloud/models/alias`	クラウド同期に公開されるモデルエイリアスの一覧を取得します
GET	`/api/assess`	最新のアセスメント分類（プロバイダー／モデルごと）を読み取ります
POST	`/api/assess`	アセスメントを実行 — 本文：`{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	`/api/evals`	組み込み評価スイートと最新の実行結果を一覧表示します
POST	`/api/evals`	評価の実行を開始します
POST	`/api/evals/suites`	カスタム評価スイートを作成 — 本文は `evalSuiteSaveSchema` によって検証されます
GET	`/api/evals/suites/[id]`	カスタム評価スイートを取得します

認証： /api/cloud/auth は Bearer キーを直接検証します。その他の /api/cloud/*、/api/evals/*、および /api/assess ルートには、管理セッションまたは API キーが必要です。/api/assess の POST は、判別可能なユニオン型のスコープスキーマとともに validateBody を使用します。

ACP（Agent Client Protocol）管理

子プロセスとして実行されます。これらのエンドポイントは、ACP エージェントの検出とカスタムエージェントの登録を管理します。

メソッド	パス	説明
GET	`/api/acp/agents`	既知のすべての CLI エージェント（組み込み + カスタム）を、インストール状態、バージョン、バイナリとともに一覧表示
POST	`/api/acp/agents`	カスタム ACP エージェントを登録、またはキャッシュを更新 — 本文: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` または `{action: "refresh"}`
DELETE	`/api/acp/agents`	カスタム ACP エージェントを削除 — クエリパラメーター: `?id=<agentId>`

レスポンス例（GET /api/acp/agents）:

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

認証: 管理セッション（ダッシュボードの auth_token cookie）または管理スコープの API キーが必要です。

詳細については、ACP フレームワークを参照してください。

分析とオブザーバビリティ

ルーティング、圧縮、プロバイダーの多様性を監視するためのリアルタイム分析エンドポイントです。これらは /dashboard/analytics/* ページで使用されます。

自動ルーティング分析

メソッド	パス	説明
GET	`/api/analytics/auto-routing`	自動ルーティングの集計統計: 総呼び出し数、戦略分布、階層分布、上位プロバイダー
GET	`/api/analytics/auto-routing?days=7`	時間枠を指定した統計（デフォルトは 24 時間）

レスポンス例:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

圧縮分析

メソッド	パス	説明
GET	`/api/analytics/compression`	圧縮の集計統計: 削減されたトークン数、削減率、モード分布、エンジン使用状況

レスポンス例:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

プロバイダー多様性の追跡

メソッド	パス	説明
GET	`/api/analytics/diversity`	Shannon エントロピーに基づく多様性追跡: プロバイダーの分散度を測定し、単一障害点を防止

レスポンス例:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI がトラフィックの 40% を占めています — 分散を検討してください"]
}

認証: 管理セッションまたは管理スコープの API キーが必要です。

管理者向け操作

運用管理用の管理者専用エンドポイント。

メソッド	パス	説明
GET	`/api/admin/concurrency`	現在の同時実行数制限（グローバルおよびプロバイダーごと）を取得
POST	`/api/admin/concurrency`	同時実行数制限を更新 — 本文: `{global?: number, perProvider?: Record<string, number>}`

認証: 管理者スコープを持つ管理セッションが必要です。

CLI ツール管理

OmniRoute と統合する CLI ツール（antigravity、chipotle、commandCode、 devin-cli など）を管理します。完全な一覧については、プロバイダーリファレンスを参照してください。

メソッド	パス	説明
GET	`/api/cli-tools/all-statuses`	すべての CLI ツールのステータス（インストール状況、バージョン、最終確認日時）
GET	`/api/cli-tools/status`	1 つの CLI ツールの詳細なステータス（`?tool=` クエリ）
POST	`/api/cli-tools/apply`	ツール用に生成された設定を書き込み（`dryRun` でプレビュー。コンテナ化されている場合は `422` + `containerEphemeralTarget`。`migration` は従来の Codex YAML を示す）
GET	`/api/cli-tools/backups`	CLI ツール設定のバックアップ一覧を取得
POST	`/api/cli-tools/backups`	すべての CLI ツール設定のバックアップを作成
POST	`/api/cli-tools/backups`	復元: 同じエンドポイントの本文に `{tool, backupId}` を指定すると、そのバックアップを復元
GET	`/api/cli-tools/antigravity-mitm`	Antigravity MITM プロキシ（「antigravity-mitm」CLI ツール）のステータス
POST	`/api/cli-tools/antigravity-mitm/alias`	antigravity-mitm のエイリアスを設定

認証: 管理セッションが必要です。

エージェントスキル

AI エージェントスキル（OpenAI のカスタム GPT に似たエージェント向け機能）を管理します。

メソッド	パス	説明
GET	`/api/agent-skills`	すべてのエージェントスキル（組み込み + カスタム）の一覧を取得
GET	`/api/agent-skills/[id]`	特定のエージェントスキルを取得
POST	`/api/agent-skills`	カスタムエージェントスキルを作成 — 本文: `{name, description, prompt, model?, temperature?}`
PUT	`/api/agent-skills/[id]`	カスタムエージェントスキルを更新
DELETE	`/api/agent-skills/[id]`	カスタムエージェントスキルを削除
GET	`/api/agent-skills/[id]/raw`	未加工のプロンプトとメタデータを取得（実行なし）
POST	`/api/agent-skills/generate`	自然言語による説明から新しいスキルを AI で生成

認証: 管理セッションまたは管理スコープの API キーが必要です。

キャッシュ管理

セマンティックキャッシュと推論キャッシュを管理します。

メソッド	パス	説明
GET	`/api/cache`	キャッシュの概要：エントリ総数、ヒット率、ディスク上のサイズ
GET	`/api/cache/entries`	キャッシュ済みエントリの一覧（ページネーション対応）
DELETE	`/api/cache/entries`	キャッシュエントリを削除（クエリパラメータでフィルタリング）
GET	`/api/cache/stats`	キャッシュの詳細統計（プロバイダー別、モデル別）
GET	`/api/cache/reasoning`	推論キャッシュの状態（推論の再現用）
DELETE	`/api/cache/reasoning`	推論キャッシュをクリア — クエリパラメータ：`?toolCallId=<id>`（単一）、`?provider=<p>`、またはパラメータなし（すべて）

認証： 管理セッションが必要です。

メモリシステム

永続メモリ（FTS5 + ベクトル埋め込み）を管理します。

メソッド	パス	説明
GET	`/api/memory`	メモリエントリの一覧（スコープ、タイプ、検索クエリでフィルタリング）
POST	`/api/memory`	新しいメモリエントリを作成 — 本文：`{scope, type, content, metadata?}`
GET	`/api/memory/[id]`	特定のメモリエントリを取得
PUT	`/api/memory/[id]`	メモリエントリを更新
DELETE	`/api/memory/[id]`	メモリエントリを削除
GET	`/api/memory?q=`	メモリを検索（FTS5 + ベクトル）— 同じレスポンスに統計情報も含まれます

認証： 管理セッションまたは管理スコープの API キーが必要です。

Webhook

イベントの Webhook サブスクリプションを管理します。

メソッド	パス	説明
GET	`/api/webhooks`	すべての Webhook サブスクリプションを一覧表示
POST	`/api/webhooks`	Webhook サブスクリプションを作成 — 本文：`{url, events[], secret?, active?}`
GET	`/api/webhooks/[id]`	特定の Webhook サブスクリプションを取得
PUT	`/api/webhooks/[id]`	Webhook サブスクリプションを更新
DELETE	`/api/webhooks/[id]`	Webhook サブスクリプションを削除
GET	`/api/webhooks/[id]/deliveries`	Webhook の配信履歴（成功／失敗ログ）を一覧表示
POST	`/api/webhooks/[id]/test`	Webhook にテストイベントを送信

認証： 管理セッションが必要です。

すべてのイベントタイプについては、Webhook フレームワークを参照してください。

Skills Framework

Skills（エージェント拡張フレームワーク）を管理します。

メソッド	パス	説明
GET	`/api/skills`	インストール済みのすべてのSkill（組み込み + カスタム）を一覧表示します
POST	`/api/skills/install`	ローカルパスまたはURLからSkillをインストールします
DELETE	`/api/skills/[id]`	Skillをアンインストールします
PUT	`/api/skills/[id]`	Skillを有効化または無効化します — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}`
POST	`/api/skills/executions`	Skillを実行します — body: `{skillName, apiKeyId, input?, sessionId?}`
GET	`/api/skills/executions`	すべてのSkillの実行履歴を一覧表示します（`?apiKeyId=`でフィルタリング）

認証: 管理セッションまたは管理スコープのAPIキーが必要です。

詳細については、Skills Frameworkを参照してください。

プラグイン

OmniRouteプラグイン（サードパーティ製拡張機能）を管理します。

メソッド	パス	説明
GET	`/api/plugins`	インストール済みのプラグインを一覧表示します
POST	`/api/plugins/marketplace/install`	マーケットプレイスからプラグインをインストールします
DELETE	`/api/plugins/[name]`	プラグインをアンインストールします
POST	`/api/plugins/[name]/activate`	プラグインを有効化します
POST	`/api/plugins/[name]/deactivate`	プラグインを無効化します
GET	`/api/plugins/[name]/config`	プラグイン設定を取得します
PUT	`/api/plugins/[name]/config`	プラグイン設定を更新します

認証: 管理セッションが必要です。

詳細については、Plugins Frameworkを参照してください。

シャドールーティング

プロバイダーのシャドー/A-B比較は、独立したRESTインターフェースではありません。コンボルーティングを通じて設定します（Auto-Comboを参照）。コンボごとの比較メトリクスは、GET /api/combos/metricsで提供されます。

ガードレール

ランタイムガードレール（PII検出、プロンプトインジェクション検出、ビジョンブリッジング）を確認します。ガードレールはすべてのリクエストで実行されます。呼び出しごとにオプトアウトするには、x-omniroute-disabled-guardrailsリクエストヘッダーを使用します。永続的な有効化/無効化を行うインターフェースはありません。

メソッド	パス	説明
GET	`/api/guardrails`	登録済みガードレールとそのステータス（名前/有効/優先度）を一覧表示します
POST	`/api/guardrails/test`	サンプル入力に対して呼び出し前パイプラインをドライランします — body: `{input, disabledGuardrails?}`

認証: 管理セッションが必要です。

詳細については、セキュリティ > ガードレールを参照してください。

認証

4つの認証情報ファミリー（ダッシュボードセッション、ローカルCLIトークン、oma_live_… Access Token、管理スコープ付きAPIキー）と、推論キーとの違いについては、管理認証を参照してください。

ダッシュボードルート（/dashboard/*）では、auth_token Cookieを使用します
ログインでは保存済みのパスワードハッシュを使用し、利用できない場合はINITIAL_PASSWORDにフォールバックします
requireLoginは/api/settings/require-login経由で切り替えられます
REQUIRE_API_KEY=trueの場合、/v1/*ルートではBearer APIキーが必要になることがあります
このリファレンスにおける「管理トークン」/「管理スコープ付きAPIキー」は、上記ガイドに記載されているファミリーのいずれかを意味し、未定義の追加シークレット種別を指すものではありません

破壊的変更（v3.8.0） — /api/v1/agents/tasks/*およびクールダウン管理エンドポイントでは、管理認証（ダッシュボードのauth_token Cookieまたは管理スコープ付きAPIキー）が必須になりました。以前、認証なしでこれらのルートを呼び出していたクライアントは、401 Unauthorizedを受け取ります。コミット588a0333（fix(auth): require management auth for agent and cooldown APIs）を参照してください。

139 KiB Raw Blame History Unescape Escape

API Reference (日本語)

目次

チャット補完

カスタムヘッダー

排他的マネージドセッションリース

x-omniroute-compression

埋め込み

画像生成

ドキュメントOCR

Azure Document Intelligenceのポーリングフロー

Vertex AI DeepSeek OCRの認証とエンドポイント解決

モデル一覧

モデル ID のプレフィックス（?prefix=）

思考なしモデルのバリアント

プロバイダープラグインマニフェスト

互換性エンドポイント

プロバイダー専用ルート

Files API

Batches API

Search API

Web Fetch API

WebSocketストリーミング

WebSocket経由のResponses API（codexのみ）

モデルID: codex/ プレフィックスなしのChatGPT IDを使用

OpenAI Codex CLIの設定

クォータと問題の報告

セルフサービスでの使用状況確認（/api/usage/om-usage）

セマンティックキャッシュ

レイテンシへの影響

キー単位のキャッシュバイパス

リクエスト単位のバイパス

ダッシュボードと管理

認証

プロバイダー管理

OAuth フロー

ルーティングと設定

使用状況と分析

設定

コンテキストと圧縮

監視

バックアップとエクスポート／インポート

クラウド同期

トンネル

CLI ツール

ACP エージェント

耐障害性とレート制限

評価

ポリシー

コンプライアンス

v1beta（Gemini 互換）

内部／システム API

OAuth 環境の修復 (v3.6.1+)

音声文字起こし

Ollama 互換性

トークン付き VS Code / ヘッダーなしエイリアス

テレメトリ

予算

トークン制限

リクエスト処理

コンボ管理

Webhook

登録済みキー（自動管理）

エージェントプロトコル

管理プロキシ

レジリエンス（拡張）

スキル

メモリ

MCP サーバー

A2A サーバー

JSON-RPC

エージェントカード

REST ヘルパー

クラウド、評価、アセスメント

ACP（Agent Client Protocol）管理

分析とオブザーバビリティ

自動ルーティング分析

圧縮分析

プロバイダー多様性の追跡

管理者向け操作

139 KiB

Raw Blame History

`x-omniroute-compression`

モデル ID のプレフィックス（`?prefix=`）

モデルID: `codex/` プレフィックスなしのChatGPT IDを使用

セルフサービスでの使用状況確認（`/api/usage/om-usage`）