OmniRoute API 参考完全指南统一端点、兼容路由与管理接口的实战解析【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文基于 OmniRoute 仓库中的 API 参考文档docs/i18n/pl/docs/reference/API_REFERENCE.md系统梳理 OmniRoute 对外暴露的全部 API 面/v1/*推理端点Chat Completions、Embeddings、图像生成、音频转写、多协议兼容路由OpenAI / Anthropic / Gemini / Ollama、语义缓存与管理类 APIProvider、用量、预算、韧性、隧道等并结合仓库源码说明请求处理流水线、幂等与缓存旁路等关键机制的实际落点帮助你在集成、排障和二次开发时快速找到对应的接口与实现证据。一、概览一个端点多种协议OmniRoute 的定位是一个自托管 AI 网关客户端只需对接一个 base URL 与一个 Bearer API Key即可访问其聚合的全部聊天、嵌入与图像模型。文档给出的默认本地地址为http://localhost:20128。其 API 面分为三大块推理端点/v1/*OpenAI 兼容的 chat / embeddings / images / audio 端点外加 Anthropic、Gemini、Ollama 等格式兼容路由管理端点/api/*Dashboard 背后的 REST 接口涵盖 Provider、密钥、组合Combo、用量、预算、韧性、备份、隧道、CLI 工具与 ACP Agent 等系统端点如/api/init、/api/restart、/api/system-info等内部与运维接口。从源码结构看/v1/*的路由以 Next.js App Router 的形式组织在 src/app/api/v1 下可以看到chat/、embeddings/、images/、audio/、messages/、responses/、providers/、relay/、batches/、search/等大量子路由目录而真正的协议转换与执行逻辑集中在open-sse包handlers、executors、translator中这与文档Request Processing一节描述的handleChat→handleChatCore→ provider executor 链路相吻合。一个值得注意的实现细节为了兼容 OpenAI 风格 SDK 的错误处理OmniRoute 为所有未知的/v1/*路径提供了一个 JSON 404 兜底路由src/app/api/v1/[...omnirouteCatchAll]/route.ts。其注释说明没有它时未知路径会落到 Dashboard 的 HTML 404 页面导致以 OpenAI 客户端身份访问的 SDK 在解析 HTML 时崩溃现在统一返回error.type not_found、code: unknown_route的标准 JSON 错误体。静态路由如/v1/models在 App Router 匹配中优先于该 catch-all因此真实端点不受影响。二、Chat Completions核心推理端点2.1 基本请求POST /v1/chat/completions Authorization: Bearer your-api-key Content-Type: application/json { model: cc/claude-opus-4-6, messages: [ {role: user, content: Write a function to...} ], stream: true }model字段支持provider/model直连写法如cc/claude-opus-4-6也支持别名与 Combo见文档Request Processing一节第 3 步。stream: true时返回 SSE 流式响应。2.2 自定义请求/响应头HeaderDirectionDescriptionX-OmniRoute-No-CacheRequestSet totrueto bypass cacheX-OmniRoute-ProgressRequestSet totruefor progress eventsX-Session-IdRequestSticky session key for external session affinityx_session_idRequestUnderscore variant also accepted (direct HTTP)Idempotency-KeyRequestDedup key (5s window)X-Request-IdRequestAlternative dedup keyX-OmniRoute-CacheResponseHITorMISS(non-streaming)X-OmniRoute-IdempotentResponsetrueif deduplicatedX-OmniRoute-ProgressResponseenabledif progress tracking onX-OmniRoute-Session-IdResponseEffective session ID used by OmniRouteNginx 注意如果你依赖下划线头例如x_session_id需要启用underscores_in_headers on;。这些头并非停留在文档层面仓库中有明确的实现佐证缓存旁路src/lib/semanticCache.ts 头部注释明确写出Bypass: X-OmniRoute-No-Cache: true即语义缓存层在读取该头为true时直接跳过缓存查找适合调试或对缓存正确性敏感的请求。幂等去重open-sse/handlers/chatCore.ts中处理Idempotency-Key/x-request-id去重键参见 open-sse/handlers/chatCore.ts#L701 附近的实现文档中5 秒窗口与该去重窗口一致去重命中时响应头会带X-OmniRoute-Idempotent: true。Relay 透传中继端点 src/app/api/v1/relay/chat/completions/route.ts 会把客户端的x-request-id原样放入上游头并注入x-relay-token-id、x-relay-client-ip保证请求在 Relay 层与内部handleChat流水线之间可追踪。2.3 内部入口handleChat主端点/v1/chat/completions的处理入口是handleChatsrc/sse/handlers/chat.ts。Relay 路由在鉴权、限流、注入防护与模型白名单校验通过后正是通过克隆请求并调用handleChat(originalRequest)转发进内部流水线随后附加X-Relay-Token、X-Routing-Backend: ts等头并异步记录用量recordRelayUsage。从该源码结构看同一套 chat 核心被直连/v1端点与Relay 中继端点两条入口复用鉴权策略API Key vs Relay Token则在各自入口层完成。三、Embeddings嵌入向量端点POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { model: nebius/Qwen/Qwen3-Embedding-8B, input: The food was delicious }支持的 ProviderNebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、OpenRouter、GitHub Models。列出全部嵌入模型# List all embedding models GET /v1/embeddings对应源码目录为 src/app/api/v1/embeddings与文档描述的POST 生成向量、GET 列出模型双用途路由一致。四、Image Generation图像生成端点POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { model: openai/gpt-image-2, prompt: A beautiful sunset over mountains, size: 1024x1024 }支持的 ProviderOpenAIGPT Image 2、xAIGrok Image、Together AIFLUX、Fireworks AI、NebiusFLUX、Hyperbolic、NanoBanana、OpenRouter、SD WebUI本地、ComfyUI本地。# List all image models GET /v1/images/generations图像模型清单与注册逻辑可在open-sse/config/imageRegistry.ts与 src/app/api/v1/images 路由目录中查证。五、List Models 与兼容性端点5.1 模型列表GET /v1/models Authorization: Bearer your-api-key → Returns all chat, embedding, and image models combos in OpenAI format一次返回聊天、嵌入、图像模型以及 Combo且统一为 OpenAI 格式方便现有 SDK 直接消费。5.2 兼容性端点总表MethodPathFormatPOST/v1/chat/completionsOpenAIPOST/v1/messagesAnthropicPOST/v1/responsesOpenAI ResponsesPOST/v1/embeddingsOpenAIPOST/v1/images/generationsOpenAIGET/v1/modelsOpenAIPOST/v1/messages/count_tokensAnthropicGET/v1beta/modelsGeminiPOST/v1beta/models/{...path}Gemini generateContentPOST/v1/api/chatOllama这些端点镜像了对应厂商的 API 格式使期望原生 SDK 体验的客户端Anthropic SDK、Gemini SDK、Ollama 客户端无需改动请求格式即可接入。仓库中可看到对应的路由目录src/app/api/v1/messages、src/app/api/v1/responses、src/app/api/v1/apiOllama 兼容等。5.3 指定 Provider 的专用路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations若请求体中的 model 前缀缺失网关会自动补上 provider 前缀若 model 与路径中的 provider 不匹配则返回400。这为强制走某个供应商的场景提供了显式控制面实现位于 src/app/api/v1/providers。5.4 Ollama 兼容对使用 Ollama API 格式客户端的适配# Chat endpoint (Ollama format) POST /v1/api/chat # Model listing (Ollama format) GET /api/tags请求会在 Ollama 格式与内部格式之间自动翻译。/api/tags返回 Ollama 兼容的模型 tag 列表见下文Internal / System APIs。5.5 Gemini v1betaEndpointMethodDescription/v1beta/modelsGETList models in Gemini format/v1beta/models/{...path}POSTGeminigenerateContentendpoint六、音频转写Audio TranscriptionPOST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data使用 Deepgram 或 AssemblyAI 转写音频文件。完整 curl 示例curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H Authorization: Bearer your-api-key \ -F filerecording.mp3 \ -F modeldeepgram/nova-3响应示例{ text: Hello, this is the transcribed audio content., task: transcribe, language: en, duration: 12.5 }支持的模型deepgram/nova-3、assemblyai/best支持的格式mp3、wav、m4a、flac、ogg、webm该端点与文档Request Processing流程中提到的handleAudioTranscription入口对应音频请求不经过 chat 核心的格式翻译响应原样返回。七、语义缓存Semantic Cache# Get cache stats GET /api/cache/stats # Clear all caches DELETE /api/cache/stats响应示例{ semanticCache: { memorySize: 42, memoryMaxSize: 500, dbSize: 128, hitRate: 0.65 }, idempotency: { activeKeys: 3, windowMs: 5000 } }字段含义memorySize/memoryMaxSize为内存缓存条目数与上限dbSize为持久化DB层条目数hitRate为命中率idempotency段返回当前活跃去重键数量与 5000ms 的去重窗口。缓存核心实现位于 src/lib/semanticCache.ts请求级旁路头X-OmniRoute-No-Cache: true即在此层生效非流式响应的X-OmniRoute-Cache: HIT/MISS头则是该层判定结果的回传。八、Dashboard 与管理 API以下接口均服务于 Dashboard 与运维脚本是 OmniRoute 的控制面全集。8.1 认证AuthenticationEndpointMethodDescription/api/auth/loginPOSTLogin/api/auth/logoutPOSTLogout/api/settings/require-loginGET/PUTToggle login required8.2 Provider 管理EndpointMethodDescription/api/providersGET/POSTList / create providers/api/providers/[id]GET/PUT/DELETEManage a provider/api/providers/[id]/testPOSTTest provider connection/api/providers/[id]/modelsGETList provider models/api/providers/validatePOSTValidate provider config/api/provider-nodes*VariousProvider node management/api/provider-modelsGET/POST/PATCH/DELETECustom models (add, update, hide/show, delete)8.3 OAuth 流程EndpointMethodDescription/api/oauth/[provider]/[action]VariousProvider-specific OAuth8.4 路由与配置EndpointMethodDescription/api/models/aliasGET/POSTModel aliases/api/models/catalogGETAll models by provider type/api/combos*VariousCombo management/api/keys*VariousAPI key management/api/pricingGETModel pricing8.5 用量与分析EndpointMethodDescription/api/usage/historyGETUsage history/api/usage/logsGETUsage logs/api/usage/request-logsGETRequest-level logs/api/usage/[connectionId]GETPer-connection usage8.6 设置SettingsEndpointMethodDescription/api/settingsGET/PUT/PATCHGeneral settings/api/settings/proxyGET/PUTNetwork proxy config/api/settings/proxy/testPOSTTest proxy connection/api/settings/ip-filterGET/PUTIP allowlist/blocklist/api/settings/thinking-budgetGET/PUTReasoning token budget/api/settings/system-promptGET/PUTGlobal system prompt8.7 监控MonitoringEndpointMethodDescription/api/sessionsGETActive session tracking/api/rate-limitsGETPer-account rate limits/api/monitoring/healthGETHealth check provider summarycatalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETECache stats / clear8.8 备份与导出/导入EndpointMethodDescription/api/db-backupsGETList available backups/api/db-backupsPUTCreate a manual backup/api/db-backupsPOSTRestore from a specific backup/api/db-backups/exportGETDownload database as .sqlite file/api/db-backups/importPOSTUpload .sqlite file to replace database/api/db-backups/exportAllGETDownload full backup as .tar.gz archive8.9 云同步Cloud SyncEndpointMethodDescription/api/sync/cloudVariousCloud sync operations/api/sync/initializePOSTInitialize sync/api/cloud/*VariousCloud management8.10 隧道TunnelsEndpointMethodDescription/api/tunnels/cloudflaredGETRead Cloudflare Quick Tunnel install/runtime status for the dashboard/api/tunnels/cloudflaredPOSTEnable or disable the Cloudflare Quick Tunnelactionenable/disable8.11 CLI 工具状态EndpointMethodDescription/api/cli-tools/claude-settingsGETClaude CLI status/api/cli-tools/codex-settingsGETCodex CLI status/api/cli-tools/droid-settingsGETDroid CLI status/api/cli-tools/openclaw-settingsGETOpenClaw CLI status/api/cli-tools/runtime/[toolId]GETGeneric CLI runtimeCLI 响应统一包含installed、runnable、command、commandPath、runtimeMode、reason便于前端区分未安装与不可运行两类状态。8.12 ACP AgentsEndpointMethodDescription/api/acp/agentsGETList all detected agents (built-in custom) with status/api/acp/agentsPOSTAdd custom agent or refresh detection cache/api/acp/agentsDELETERemove a custom agent byidquery paramGET 响应包含agents[]每项含id、name、binary、version、installed、protocol、isCustom与summarytotal、installed、notFound、builtIn、custom。8.13 韧性与限流Resilience Rate LimitsEndpointMethodDescription/api/resilienceGET/PATCHGet/update request queue, connection cooldown, provider breaker, and wait settings/api/resilience/resetPOSTReset provider circuit breakers/api/rate-limitsGETPer-account rate limit status/api/rate-limitGETGlobal rate limit configuration8.14 评测与策略EvalsEndpointMethodDescription/api/evalsGET/POSTList eval suites / run evaluationPoliciesEndpointMethodDescription/api/policiesGET/POST/DELETEManage routing policiesComplianceEndpointMethodDescription/api/compliance/audit-logGETCompliance audit log (last N)8.15 内部 / 系统 APIEndpointMethodDescription/api/initGETApplication initialization check (used on first run)/api/tagsGETOllama-compatible model tags (for Ollama clients)/api/restartPOSTTrigger graceful server restart/api/shutdownPOSTTrigger graceful server shutdown/api/system/env/repairPOSTRepair OAuth provider environment variables/api/system-infoGETGenerate system diagnostics report注意这些端点由系统内部使用或用于 Ollama 客户端兼容一般不由终端用户直接调用。8.16 OAuth 环境变量修复v3.6.1POST /api/system/env/repair Content-Type: application/json { provider: claude-code }用于修复某个 Provider 缺失或损坏的 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 }修复前会自动生成环境备份文件backupPath降低误操作风险。九、遥测Telemetry# Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary响应示例{ providers: { claudeCode: { p50: 245, p95: 890, p99: 1200, count: 150 }, github: { p50: 180, p95: 620, p99: 950, count: 320 } } }按 Provider 维度给出延迟分位数与样本数可据此评估各上游的实时健康状况并辅助路由调优。十、预算Budget# Get budget status for all API keys GET /api/usage/budget # Set or update a budget POST /api/usage/budget Content-Type: application/json { keyId: key-123, limit: 50.00, period: monthly }按 API Key 粒度设置用量预算限额 周期与/api/keys*的密钥管理形成配套的多租户成本控制手段。十一、请求处理流水线Request Processing文档将一次请求的完整生命周期概括为 9 步Client sends request to/v1/*Route handler callshandleChat,handleEmbedding,handleAudioTranscription, orhandleImageGenerationModel is resolved (direct provider/model or alias/combo)Credentials selected from local DB with account availability filteringFor chat:handleChatCore— format detection, translation, cache check, idempotency checkProvider executor sends upstream requestResponse translated back to client format (chat) or returned as-is (embeddings/images/audio)Usage/logging recordedFallback applies on errors according to combo rules从源码结构看这条链路与仓库实现一一对应步骤 2 的入口函数位于src/sse/handlers/如 src/sse/handlers/chat.tsRelay 入口 src/app/api/v1/relay/chat/completions/route.ts 中const response await handleChat(originalRequest)即为该调用的实例步骤 5 的handleChatCore位于 open-sse/handlers/chatCore.ts承担格式检测、翻译、缓存检查联动 src/lib/semanticCache.ts与幂等检查步骤 9 的 Combo 故障回退规则由/api/combos*管理的配置驱动测试路由 src/app/api/combos/test/route.ts 同样复用了handleChat入口便于在管理界面直接验证 Combo 行为。更完整的架构背景可参阅 docs/architecture/ARCHITECTURE.md。十二、认证AuthenticationDashboard 路由/dashboard/*使用auth_tokenCookie登录校验保存的密码哈希回退到INITIAL_PASSWORD环境变量是否强制登录可通过/api/settings/require-login开关切换requireLogin/v1/*路由在REQUIRE_API_KEYtrue时可选地要求 Bearer API Key。即管理面走会话 Cookie推理面走 Bearer Key两套凭证互不混用。十三、集成与排障要点小结未知路径排查若 SDK 收到error.type: not_found的 JSON 而非 HTML 404说明请求到达了 OmniRoute 但路径不被支持应核对 base URL 与端点对应 src/app/api/v1/[...omnirouteCatchAll]/route.ts 的兜底行为。缓存干扰调试阶段用X-OmniRoute-No-Cache: true排除语义缓存影响再用GET /api/cache/stats查看命中率验证是否生效需要彻底清空时调用DELETE /api/cache/stats。重复请求为写类客户端如批量脚本附加Idempotency-Key或X-Request-Id5 秒窗口内重复请求会去重并以X-OmniRoute-Idempotent: true标记。上游延迟定位结合GET /api/telemetry/summary的分位数与/api/monitoring/health的 provider 汇总判断问题是集中在某个上游还是本地网关。多协议客户端OpenAI SDK 走/v1/chat/completionsAnthropic SDK 走/v1/messagesGemini SDK 走/v1beta/*Ollama 客户端走/v1/api/chatGET /api/tags均无需改造请求体。以上即 OmniRoute 当前仓库 API 面的完整参考。端点行为以本文引用的源码文件为准管理面细节可在src/app/api/对应路由目录中进一步查证。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考