OmniRoute API 参考详解从 Chat Completions 到管理端点的完整接口体系与请求处理链路【免费下载链接】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 参考文档为主线完整梳理其全部对外接口OpenAI/Anthropic/Gemini/Ollama 兼容端点、嵌入与图像生成、语义缓存、Dashboard 管理面Provider、密钥、预算、隧道、备份、遥测与请求处理流水线。读完你可以直接基于文档中的端点表、请求示例和响应结构对接 OmniRoute并借助仓库源码验证每个关键机制缓存键生成、幂等去重、会话亲和、鉴权策略的真实实现。一、端点总览OmniRoute 的 API 面可以分成两大类/v1/*与/v1beta/*面向 LLM 客户端的数据面chat、embeddings、images、responses、messages 等对应路由位于 src/app/api/v1/ 与 src/app/api/v1beta/ 下/api/*面向 Dashboard 与管理场景的控制面Provider 管理、密钥、用量、设置、备份、隧道、遥测等对应路由位于 src/app/api/ 下。请求处理总流程文档定义客户端向/v1/*发送请求路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直接 provider/model 或别名/combo从本地数据库选择凭据并按账户可用性过滤chat 场景进入handleChatCore——格式检测、翻译、缓存检查、幂等检查Provider executor 向上游发送请求响应翻译回客户端格式chat或原样返回embeddings/images/audio记录用量与日志出错时按 combo 规则应用 fallback。完整架构参考见 docs/architecture/ARCHITECTURE.md。二、Chat Completions 与自定义请求头基础调用示例文档原文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 }自定义 HeadersHeader方向说明X-OmniRoute-No-CacheRequest设为true绕过缓存X-OmniRoute-ProgressRequest设为true开启进度事件X-Session-IdRequest外部会话亲和的粘性会话键x_session_idRequest下划线变体同样被接受直接 HTTPIdempotency-KeyRequest去重键5s 窗口X-Request-IdRequest替代去重键X-OmniRoute-CacheResponseHIT或MISS非流式X-OmniRoute-IdempotentResponse被去重时返回trueX-OmniRoute-ProgressResponse进度追踪开启时返回enabledX-OmniRoute-Session-IdResponseOmniRoute 实际使用的有效会话 IDNginx 提示如果依赖下划线头如x_session_id需开启underscores_in_headers on;。源码级验证上述头部机制在 src/app/api/v1/chat/completions/route.ts 中有直接印证会话亲和路由在入口处调用resolveSessionId(request)与admitChatRequest(request, { sessionId, queueMs: CHAT_ADMISSION_QUEUE_MAX_MS })来自/shared/middleware/chatBodyAdmission。这意味着X-Session-Id不仅决定粘性路由还参与准入admission排队控制队列超过上限的请求会直接被拒而不是拖垮进程。Content-Type 守卫对非application/json的 POST body 直接返回415unsupported_media_type与 OpenAI/Anthropic 边缘行为保持一致防止text/plainbody 悄悄进入 provider 解析流程。宽松的前置 schema路由只断言非 null 对象、model若存在须为可空字符串、messages若存在须为数组zod.passthrough()把真正的深度校验temperature/top_p/max_tokens/n 等下沉给handleChat以避免在热路径上新增拒绝行为。注入防护路由持有一个单例createInjectionGuard提示注入检测在handleChat内与 pino logger 一并重评估避免重复打日志。三、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。列出全部嵌入模型GET /v1/embeddings源码印证src/app/api/v1/embeddings/route.tsGET /v1/embeddings通过getSpecialtyModelsResponse过滤model.type embedding的目录条目即文档所说的列出全部嵌入模型POST先用v1EmbeddingsSchema做 body 校验失败返回 400鉴权遵循REQUIRE_API_KEY特性开关关闭时忽略非法 key 以保证匿名访问可用开启时先校验 key 有效性401再调用enforceApiKeyPolicy强制模型访问限制与预算上限——这是 API key 策略在数据面上的落点。四、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本地。列出全部图像模型GET /v1/images/generations五、List ModelsGET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回全部 chat、embedding、image 模型 combos路由实现在 src/app/api/v1/models/目录构建拆分为 catalog 分页、去重、OpenRouter 映射、付费过滤、视觉能力标注等模块最终按 OpenAI/v1/models格式输出因此标准 OpenAI 客户端可以零改造地列出 OmniRoute 中的全部可用模型含 combo。六、兼容端点Compatibility EndpointsMethodPath格式POST/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指定 Provider 直连路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations若模型名缺少 provider 前缀会自动补全模型与 provider 不匹配时返回400。这组路由在 src/app/api/v1/providers/[provider]/ 下实现为绕过路由表直接打到指定上游的客户端提供了稳定入口。七、语义缓存Semantic Cache# 获取缓存统计 GET /api/cache/stats # 清空全部缓存 DELETE /api/cache/stats响应示例{ semanticCache: { memorySize: 42, memoryMaxSize: 500, dbSize: 128, hitRate: 0.65 }, idempotency: { activeKeys: 3, windowMs: 5000 } }源码级实现src/lib/semanticCache.ts文件头注释完整定义了缓存语义可与文档互相印证两级结构内存 LRU快路径 SQLite跨重启持久化缓存键SHA-256(model 归一化 messages temperature top_p)且只对temperature0的响应缓存流式兼容流式响应在组装完成后入缓存命中时一律返回 JSON绕过方式请求头X-OmniRoute-No-Cache: true持久指标cache_metrics表维护hits/misses/tokens_saved三个计数器/api/cache/stats的hitRate即由此得出。管理端点 src/app/api/cache/stats/route.ts 对 GET/DELETE 均先执行isAuthenticated鉴权未认证返回 401DELETE 成功后返回{ success: true, message: Cache cleared }。八、Dashboard 与管理端点认证端点Method说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT切换是否强制登录Provider 管理端点Method说明/api/providersGET/POST列出 / 创建 Provider/api/providers/[id]GET/PUT/DELETE管理单个 Provider/api/providers/[id]/testPOST测试 Provider 连接/api/providers/[id]/modelsGET列出 Provider 的模型/api/providers/validatePOST校验 Provider 配置/api/provider-nodes*VariousProvider 节点管理/api/provider-modelsGET/POST/PATCH/DELETE自定义模型增、改、隐藏/显示、删OAuth 流程端点Method说明/api/oauth/[provider]/[action]VariousProvider 特定的 OAuth路由与配置端点Method说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按 provider type 列出全部模型/api/combos*VariousCombo 管理/api/keys*VariousAPI 密钥管理/api/pricingGET模型定价用量与分析端点Method说明/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET按连接的用量设置端点Method说明/api/settingsGET/PUT/PATCH通用设置/api/settings/proxyGET/PUT网络代理配置/api/settings/proxy/testPOST测试代理连接/api/settings/ip-filterGET/PUTIP 白名单/黑名单/api/settings/thinking-budgetGET/PUT推理 token 预算/api/settings/system-promptGET/PUT全局 system prompt监控端点Method说明/api/sessionsGET活跃会话追踪/api/rate-limitsGET按账户的速率限制/api/monitoring/healthGET健康检查 Provider 摘要catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空备份与导出/导入端点Method说明/api/db-backupsGET列出可用备份/api/db-backupsPUT创建手动备份/api/db-backupsPOST从指定备份恢复/api/db-backups/exportGET下载数据库为 .sqlite 文件/api/db-backups/importPOST上传 .sqlite 文件替换数据库/api/db-backups/exportAllGET下载完整备份为 .tar.gz 压缩包云同步端点Method说明/api/sync/cloudVarious云同步操作/api/sync/initializePOST初始化同步/api/cloud/*Various云管理隧道端点Method说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 的安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI 工具端点Method说明/api/cli-tools/claude-settingsGETClaude CLI 状态/api/cli-tools/codex-settingsGETCodex CLI 状态/api/cli-tools/droid-settingsGETDroid CLI 状态/api/cli-tools/openclaw-settingsGETOpenClaw CLI 状态/api/cli-tools/runtime/[toolId]GET通用 CLI 运行时CLI 响应包含字段installed、runnable、command、commandPath、runtimeMode、reason。ACP Agents端点Method说明/api/acp/agentsGET列出全部已检测 agent内置 自定义及其状态/api/acp/agentsPOST添加自定义 agent 或刷新检测缓存/api/acp/agentsDELETE通过idquery 参数移除自定义 agentGET 响应包含agents[]id、name、binary、version、installed、protocol、isCustom与summarytotal、installed、notFound、builtIn、custom。弹性与速率限制端点Method说明/api/resilienceGET/PATCH获取/更新请求队列、连接冷却、Provider 熔断器与等待设置/api/resilience/resetPOST重置 Provider 熔断器/api/rate-limitsGET按账户的速率限制状态/api/rate-limitGET全局速率限制配置Evals端点Method说明/api/evalsGET/POST列出 eval 套件 / 运行评估策略Policies端点Method说明/api/policiesGET/POST/DELETE管理路由策略合规Compliance端点Method说明/api/compliance/audit-logGET合规审计日志最近 N 条v1betaGemini 兼容端点Method说明/v1beta/modelsGET以 Gemini 格式列出模型/v1beta/models/{...path}POSTGeminigenerateContent端点这些端点镜像 Gemini 的 API 格式供期望原生 Gemini SDK 兼容性的客户端使用。内部 / 系统 API端点Method说明/api/initGET应用初始化检查首次运行时使用/api/tagsGETOllama 兼容的模型 tags供 Ollama 客户端/api/restartPOST触发服务器优雅重启/api/shutdownPOST触发服务器优雅关闭/api/system/env/repairPOST修复 OAuth Provider 环境变量/api/system-infoGET生成系统诊断报告注意这些端点供系统内部或 Ollama 客户端兼容使用终端用户通常不会直接调用。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 }九、音频转写Audio TranscriptionPOST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data使用 Deepgram 或 AssemblyAI 转写音频文件。请求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 }支持的 Providerdeepgram/nova-3、assemblyai/best。支持的格式mp3、wav、m4a、flac、ogg、webm。路由实现在 src/app/api/v1/audio/transcriptions/route.ts由handleAudioTranscription处理。十、Ollama 兼容面向使用 Ollama API 格式如ollamaCLI、Open WebUI 等的客户端# 对话端点Ollama 格式 POST /v1/api/chat # 模型列表Ollama 格式 GET /api/tags请求会在 Ollama 格式与内部格式之间自动转译无需客户端做任何适配。十一、遥测Telemetry# 获取延迟遥测摘要按 provider 的 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 } } }该端点为路由决策与容量规划提供了按 Provider 分位的延迟基线。十二、预算Budget# 获取所有 API key 的预算状态 GET /api/usage/budget # 设置或更新预算 POST /api/usage/budget Content-Type: application/json { keyId: key-123, limit: 50.00, period: monthly }预算是 API key 策略的一部分如第三节源码所示/v1/*数据面每次请求都会经enforceApiKeyPolicy校验模型访问限制与预算上限超限时直接拒绝因此预算约束在网关层即时生效而不是事后统计。十三、鉴权模型Authentication文档定义的鉴权规则Dashboard 路由/dashboard/*使用auth_tokencookie登录使用已保存的密码哈希回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login切换/v1/*路由在REQUIRE_API_KEYtrue时要求 Bearer API key。源码印证src/app/api/v1/embeddings/route.ts 中isRequireApiKeyEnabled()为假时匿名可用、为真时缺失/无效 key 均返回 401且注释明确说明该行为在所有客户端 API间保持一致管理面端点如 src/app/api/cache/stats/route.ts统一先过isAuthenticated未认证返回 401缓存/统计类只读端点也受同一鉴权约束避免敏感运营数据裸奔。十四、总结OmniRoute 的 API 参考覆盖了三条主线数据面以 OpenAI 格式为核心/v1/chat/completions、/v1/embeddings、/v1/images/generations、/v1/models叠加 Anthropic/v1/messages、OpenAI Responses、Gemini/v1beta、Ollama/v1/api/chat的格式兼容层并通过/v1/providers/{provider}/*提供指定上游直连增强机制语义缓存X-OmniRoute-Cache: HIT/MISS/api/cache/stats、幂等去重Idempotency-Key5s 窗口、会话亲和X-Session-Id、进度事件X-OmniRoute-Progress控制面从 Provider/密钥/预算到备份、隧道、遥测、系统重启的完整管理端点集全部纳入 Dashboard 鉴权体系。结合仓库源码src/app/api/v1/、src/lib/semanticCache.ts、src/app/api/cache/stats/route.ts可以确认文档中描述的头部语义、鉴权开关与缓存键规则均有对应的实现代码与持久化指标支撑可作为对接与排障的可靠依据。【免费下载链接】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），仅供参考