news 2026/9/14 2:05:25

OmniRoute API 参考完全指南：统一端点、兼容路由与管理接口的实战解析

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
OmniRoute API 参考完全指南：统一端点、兼容路由与管理接口的实战解析

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, RTK+Caveman 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）、语义缓存与管理类 API（Provider、用量、预算、韧性、隧道等），并结合仓库源码说明请求处理流水线、幂等与缓存旁路等关键机制的实际落点，帮助你在集成、排障和二次开发时快速找到对应的接口与实现证据。

一、概览：一个端点，多种协议

OmniRoute 的定位是一个自托管 AI 网关：客户端只需对接一个 base URL 与一个 Bearer API Key，即可访问其聚合的全部聊天、嵌入与图像模型。文档给出的默认本地地址为http://localhost:20128。

其 API 面分为三大块：

  1. 推理端点（/v1/*）：OpenAI 兼容的 chat / embeddings / images / audio 端点，外加 Anthropic、Gemini、Ollama 等格式兼容路由；
  2. 管理端点（/api/*）：Dashboard 背后的 REST 接口，涵盖 Provider、密钥、组合（Combo）、用量、预算、韧性、备份、隧道、CLI 工具与 ACP Agent 等；
  3. 系统端点：如/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 自定义请求/响应头

HeaderDirectionDescription
X-OmniRoute-No-CacheRequestSet totrueto bypass cache
X-OmniRoute-ProgressRequestSet totruefor progress events
X-Session-IdRequestSticky session key for external session affinity
x_session_idRequestUnderscore variant also accepted (direct HTTP)
Idempotency-KeyRequestDedup key (5s window)
X-Request-IdRequestAlternative dedup key
X-OmniRoute-CacheResponseHITorMISS(non-streaming)
X-OmniRoute-IdempotentResponsetrueif deduplicated
X-OmniRoute-ProgressResponseenabledif progress tracking on
X-OmniRoute-Session-IdResponseEffective session ID used by OmniRoute

Nginx 注意：如果你依赖下划线头（例如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的处理入口是handleChat（src/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" }

支持的 Provider：Nebius、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" }

支持的 Provider：OpenAI（GPT Image 2）、xAI（Grok Image）、Together AI（FLUX）、Fireworks AI、Nebius（FLUX）、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 兼容性端点总表

MethodPathFormat
POST/v1/chat/completionsOpenAI
POST/v1/messagesAnthropic
POST/v1/responsesOpenAI Responses
POST/v1/embeddingsOpenAI
POST/v1/images/generationsOpenAI
GET/v1/modelsOpenAI
POST/v1/messages/count_tokensAnthropic
GET/v1beta/modelsGemini
POST/v1beta/models/{...path}Gemini generateContent
POST/v1/api/chatOllama

这些端点镜像了对应厂商的 API 格式，使期望"原生 SDK 体验"的客户端（Anthropic SDK、Gemini SDK、Ollama 客户端）无需改动请求格式即可接入。仓库中可看到对应的路由目录：src/app/api/v1/messages、src/app/api/v1/responses、src/app/api/v1/api（Ollama 兼容）等。

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 v1beta

EndpointMethodDescription
/v1beta/modelsGETList models in Gemini format
/v1beta/models/{...path}POSTGeminigenerateContentendpoint

六、音频转写（Audio Transcription）

POST /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 "file=@recording.mp3" \ -F "model=deepgram/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 认证（Authentication）

EndpointMethodDescription
/api/auth/loginPOSTLogin
/api/auth/logoutPOSTLogout
/api/settings/require-loginGET/PUTToggle login required

8.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 OAuth

8.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 pricing

8.5 用量与分析

EndpointMethodDescription
/api/usage/historyGETUsage history
/api/usage/logsGETUsage logs
/api/usage/request-logsGETRequest-level logs
/api/usage/[connectionId]GETPer-connection usage

8.6 设置（Settings）

EndpointMethodDescription
/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 prompt

8.7 监控（Monitoring）

EndpointMethodDescription
/api/sessionsGETActive session tracking
/api/rate-limitsGETPer-account rate limits
/api/monitoring/healthGETHealth check + provider summary（catalogCount、configuredCount、activeCount、monitoredCount）
/api/cache/statsGET/DELETECache stats / clear

8.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 archive

8.9 云同步（Cloud Sync）

EndpointMethodDescription
/api/sync/cloudVariousCloud sync operations
/api/sync/initializePOSTInitialize sync
/api/cloud/*VariousCloud management

8.10 隧道（Tunnels）

EndpointMethodDescription
/api/tunnels/cloudflaredGETRead Cloudflare Quick Tunnel install/runtime status for the dashboard
/api/tunnels/cloudflaredPOSTEnable or disable the Cloudflare Quick Tunnel（action=enable/disable）

8.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 runtime

CLI 响应统一包含：installed、runnable、command、commandPath、runtimeMode、reason，便于前端区分"未安装"与"不可运行"两类状态。

8.12 ACP Agents

EndpointMethodDescription
/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 param

GET 响应包含agents[]（每项含id、name、binary、version、installed、protocol、isCustom）与summary（total、installed、notFound、builtIn、custom）。

8.13 韧性与限流（Resilience & Rate Limits）

EndpointMethodDescription
/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 configuration

8.14 评测与策略

Evals

EndpointMethodDescription
/api/evalsGET/POSTList eval suites / run evaluation

Policies

EndpointMethodDescription
/api/policiesGET/POST/DELETEManage routing policies

Compliance

EndpointMethodDescription
/api/compliance/audit-logGETCompliance audit log (last N)

8.15 内部 / 系统 API

EndpointMethodDescription
/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.1+）

POST /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 步：

  1. Client sends request to/v1/*
  2. Route handler callshandleChat,handleEmbedding,handleAudioTranscription, orhandleImageGeneration
  3. Model is resolved (direct provider/model or alias/combo)
  4. Credentials selected from local DB with account availability filtering
  5. For chat:handleChatCore— format detection, translation, cache check, idempotency check
  6. Provider executor sends upstream request
  7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
  8. Usage/logging recorded
  9. Fallback applies on errors according to combo rules

从源码结构看，这条链路与仓库实现一一对应：

  • 步骤 2 的入口函数位于src/sse/handlers/（如 src/sse/handlers/chat.ts），Relay 入口 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。

十二、认证（Authentication）

  • Dashboard 路由（/dashboard/*）使用auth_tokenCookie；
  • 登录校验保存的密码哈希，回退到INITIAL_PASSWORD环境变量；
  • 是否强制登录可通过/api/settings/require-login开关切换（requireLogin）；
  • /v1/*路由在REQUIRE_API_KEY=true时可选地要求 Bearer API Key。

即：管理面走会话 Cookie，推理面走 Bearer Key，两套凭证互不混用。

十三、集成与排障要点小结

  1. 未知路径排查：若 SDK 收到error.type: "not_found"的 JSON 而非 HTML 404，说明请求到达了 OmniRoute 但路径不被支持，应核对 base URL 与端点（对应 src/app/api/v1/[...omnirouteCatchAll]/route.ts 的兜底行为）。
  2. 缓存干扰：调试阶段用X-OmniRoute-No-Cache: true排除语义缓存影响，再用GET /api/cache/stats查看命中率验证是否生效；需要彻底清空时调用DELETE /api/cache/stats。
  3. 重复请求：为写类客户端（如批量脚本）附加Idempotency-Key或X-Request-Id，5 秒窗口内重复请求会去重并以X-OmniRoute-Idempotent: true标记。
  4. 上游延迟定位：结合GET /api/telemetry/summary的分位数与/api/monitoring/health的 provider 汇总，判断问题是集中在某个上游还是本地网关。
  5. 多协议客户端：OpenAI SDK 走/v1/chat/completions，Anthropic SDK 走/v1/messages，Gemini SDK 走/v1beta/*，Ollama 客户端走/v1/api/chat+GET /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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/14 2:04:59

LSB隐写从原理到实战：LSB替换、位平面分析与Python实现

简介：面向信息安全初学者与图像隐写研究者的MATLAB实现资源，聚焦LSB替换隐写：通过修改图像像素最低有效位完成秘密信息嵌入，并可从载体图中逆向提取。压缩包为zip格式，共5个文件，含LSBmain.m主程序、LSB_en…

作者头像 李华
网站建设 2026/9/14 2:04:56

昆虫目标计数系统：HSV增强+注意力CNN+DBSCAN聚类

简介：这是一套面向计算机相关专业本科生的毕业设计级昆虫识别与计数系统，聚焦图像分类与目标计数在农业病虫害监测等实际场景中的落地应用，适合具备Python基础与机器学习入门知识的学习者开展课程设计或科研实践。资源共197个文件&#xff0c…

作者头像 李华
网站建设 2026/9/14 2:03:47

垃圾目标检测数据集构建实战：从类别体系到YOLOv8训练

简介：这是一套面向计算机视觉与人工智能领域的目标检测数据集，聚焦电池、纸团、一次性杯子、塑料瓶和积木五类常见垃圾目标，采用COCO格式进行标注，每张图像均包含边界框信息，可直接服务于YOLO、SSD、Faster R-CNN等主流…

作者头像 李华
网站建设 2026/9/14 2:03:03

VxWorks逆向实战：工控安全中的固件分析四层穿透法

1. 这不是教你怎么“黑”设备，而是带你真正看懂工控系统的心跳 VxWorks——这三个字母在工控安全圈里，几乎等同于“高危但沉默的动脉”。它不像Windows那样天天弹窗、打补丁、被勒索软件盯上；它常年运行在电厂DCS控制柜里、地铁信号继电器背后…

作者头像 李华