OmniRoute 网关 API 完整参考从/v1推理接口到 Dashboard 管理端点【免费下载链接】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 的完整参考指南覆盖公开的/v1推理面Chat Completions、Embeddings、Image Generation、模型列表与多协议兼容端点以及最常用的管理面Dashboard 的 Provider、Usage、Settings、Monitoring、Resilience 等管理端点。读完本文你将掌握如何用任意 OpenAI 风格客户端接入 OmniRoute 单端点网关、如何利用自定义响应头做缓存/幂等/会话控制、如何通过语义缓存与管理 API 观测与运维网关。文档正文以 docs/i18n/ru/docs/reference/API_REFERENCE.md及其英文完整版 docs/reference/API_REFERENCE.md为主体全部路由实现可对照仓库路由树src/app/api/与机器可读的 docs/openapi.yaml。基本约定OmniRoute 把全部上游 ProviderClaude、GPT、Gemini、GLM、DeepSeek、MiniMax 等收敛到一个端点客户端只需把base_url指向网关本地默认http://localhost:20128并在请求中使用provider/model形式的模型 ID例如cc/claude-opus-4-6。认证方面/v1/*推理路由在REQUIRE_API_KEYtrue时要求携带Authorization: Bearer your-api-key/api/*管理路由除公开的登录等少数端点不接受普通推理 API Key需要管理级凭据详见下文「Dashboard Management」与 docs/guides/MANAGEMENT-AUTH.md。Chat Completions最核心的聊天补全端点与 OpenAI 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 }从源码看该路由src/app/api/v1/chat/completions/route.ts是网关最热的路径处理顺序依次为Content-Type守卫非application/json直接返回415、容量准入队列admitChatRequest、请求体形状的宽松校验仅断言model与messages的顶层形状深层校验交由handleChat、提示注入守卫injectionGuard、模型别名解析resolveModelAliasWithSeedFallbackOnBody最后交给 src/sse/handlers/chat.ts 的handleChat走完整路由管线。流式请求stream: true或Accept头强制还会被withEarlyStreamKeepalive包裹在首个字节前向客户端发送 keepalive/startup 帧避免代理链路超时。Custom HeadersOmniRoute 通过一组X-OmniRoute-*自定义请求/响应头暴露缓存、进度、会话与幂等控制Header方向说明X-OmniRoute-No-Cache请求设为true绕过缓存X-OmniRoute-Progress请求设为true开启进度事件X-Session-Id请求外部会话亲和性的 sticky session 键x_session_id请求下划线变体直连 HTTP 时同样接受Idempotency-Key请求去重键5 秒窗口X-Request-Id请求备选去重键X-OmniRoute-Cache响应HIT或MISS非流式X-OmniRoute-Idempotent响应若已去重则为trueX-OmniRoute-Progress响应若开启进度跟踪则为enabledX-OmniRoute-Session-Id响应OmniRoute 实际使用的会话 IDNginx 提示如果依赖下划线请求头如x_session_id需在 Nginx 配置中开启underscores_in_headers on;否则该头会被丢弃。英文完整版还补充了若干成本遥测响应头非流式成功响应会携带X-OmniRoute-Response-CostUSD固定 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。这些头不仅由 chat completions 发出也由/v1/responses、/v1/messages及媒体端点embeddings、images、audio、rerank、videos、music、moderations发出。缓存命中成本语义语义缓存 HITX-OmniRoute-Cache-Hit: true时不发生上游调用因此X-OmniRoute-Response-Cost为 0命中服务的增量成本原本会产生或本应产生的成本单独由X-OmniRoute-Cost-Saved报告——账单消费者应累加Response-Cost命中不计费缓存分析则可聚合Cost-Saved。EmbeddingsOpenAI 兼容的向量化端点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。模型目录 ID 统一采用provider/model形式。# 列出全部 embedding 模型 GET /v1/embeddings英文完整版指出注册表中声明支持多模态的模型还可接收最多 32 个 Provider 无关的结构化条目媒体条目类型为text、image、audio、video、document其媒体source为{type:url,url:https://...}或{type:base64,data:...,media_type:...}Jina v5 Omni 系列jina-ai/jina-embeddings-v5-omni-*还会将 Jina 原生的 EmbeddingsV5Request 文档原样转发至https://api.jina.ai/v1/embeddings。安全与传输边界远程媒体 URL 必须是公网 HTTPS服务端会做重定向校验、超时、大小限制与公网 DNS 校验后再内联内联 base64 媒体每条目上限 8 MiB解码后、跨请求总计 16 MiB。不支持模态组合的模型/请求返回 HTTP 400。Image GenerationOpenAI 兼容的图片生成端点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/generationsList Models一次性获取全部可路由的模型与组合GET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回所有 chat、embedding、image 模型 combos英文完整版补充了模型 ID 前缀的三种广告模式受MODELS_CATALOG_PREFIX_MODE特性开关控制也可用?prefix按请求覆盖dual同时输出cc/claude-sonnet-4-6与claude/claude-sonnet-4-6默认、alias每模型只输出短别名一个 ID如cc/…适合模型选择器、canonical只输出完整 Provider ID 前缀。对于支持 thinking 的 Claude 模型目录还会额外广告一个claude-3-omniroute-no-thinking/provider/model变体——选择该 ID 即会在/v1/messages路径附加thinking:{type:disabled}、在/v1/chat/completions路径剔除reasoning/reasoning_effort字段从而在支持 thinking 但不希望思考的调用中压制推理。Compatibility Endpoints除 OpenAI 格式外网关还直接提供以下多协议兼容端点方法路径格式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因此 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot、Gemini SDK、Ollama 客户端都可以直接指向同一个网关端口而无需改协议。Dedicated Provider Routes如需显式锁定某个 Provider可使用专用路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generationsProvider 前缀在缺失时会被自动补全若请求中的模型与路径指定的 Provider 不匹配返回400。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/app/api/cache/stats/route.ts 的GET先经isAuthenticated校验再调用 src/lib/semanticCache.ts 的getCacheStats()内存统计取自getMemoryCache().getStats()dbSize通过对 SQLitesemantic_cache表执行SELECT COUNT(*) ... WHERE expires_at ?得出hitRate由hits / (hits misses)计算并额外返回tokensSaved与dbEntriesDELETE则清空内存缓存、清空semantic_cache表并重置cache_metrics。英文完整版还给出两条缓存语义要点延迟影响HIT 响应不经过上游X-OmniRoute-Response-Latency接近零。延迟敏感客户端基准测试、p50/p99 监控应检查X-OmniRoute-Cache-Latency头synthetic表示响应来自缓存、非真实上游耗时该头缺失表示来自真实上游调用。按 Key 绕过API Key 可通过cacheDefaultMode: bypass在POST /api/keys或PATCH /api/keys/[id]时设置跳过缓存查找、始终命中上游默认legacy为正常缓存行为。任何请求还可通过X-OmniRoute-No-Cache: true按请求绕过缓存与 Key 设置无关。Dashboard Management以下/api/*管理路由公开的登录端点除外不由普通推理 API Key 授权需要管理级凭据其凭据族、作用域与 curl 示例见 docs/guides/MANAGEMENT-AUTH.md。监控相关的扩展指标含credentialHealth见 docs/ops/MONITORING_GUIDE.md。Authentication端点方法说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT切换是否必须登录Provider Management端点方法说明/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*多种Provider 节点管理/api/provider-modelsGET/POST/PATCH/DELETE自定义模型增、改、隐藏/显示、删OAuth Flows端点方法说明/api/oauth/[provider]/[action]多种Provider 专属 OAuthRouting Config端点方法说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按 Provider 类型的全部模型/api/combos*多种Combo组合路由管理/api/keys*多种API Key 管理/api/pricingGET模型定价Usage Analytics端点方法说明/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET单连接用量Settings端点方法说明/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全局系统提示词Monitoring端点方法说明/api/sessionsGET活跃会话跟踪/api/rate-limitsGET每账户限流/api/monitoring/healthGET健康检查 Provider 汇总catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空Backup Export/Import端点方法说明/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下载完整备份Cloud Sync端点方法说明/api/sync/cloud多种云同步操作/api/sync/initializePOST初始化同步/api/cloud/*多种云端管理Tunnels端点方法说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI Tools端点方法说明/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端点方法说明/api/acp/agentsGET列出全部检测到的 Agent内置 自定义及状态/api/acp/agentsPOST添加自定义 Agent 或刷新检测缓存/api/acp/agentsDELETE按id查询参数移除自定义 AgentGET 响应包含agents[]id、name、binary、version、installed、protocol、isCustom与summarytotal、installed、notFound、builtIn、custom。Resilience Rate Limits端点方法说明/api/resilienceGET/PATCH读取/更新请求队列、连接冷却、Provider 熔断器与等待设置/api/resilience/resetPOST重置 Provider 熔断器/api/rate-limitsGET每账户限流状态/api/rate-limitGET全局限流配置Evals端点方法说明/api/evalsGET/POST列出评测套件 / 运行评测Policies端点方法说明/api/policiesGET/POST/DELETE管理路由策略Compliance端点方法说明/api/compliance/audit-logGET合规审计日志最近 N 条v1betaGemini 兼容端点方法说明/v1beta/modelsGET以 Gemini 格式列出模型/v1beta/models/{...path}POSTGeminigenerateContent端点这些端点镜像 Gemini 的 API 格式供期望原生 Gemini SDK 兼容性的客户端使用。Internal / System APIs端点方法说明/api/initGET应用初始化检查首次运行时使用/api/tagsGETOllama 兼容的模型标签供 Ollama 客户端/api/restartPOST触发优雅重启/api/shutdownPOST触发优雅关闭/api/system/env/repairPOST修复 OAuth Provider 环境变量/api/system-infoGET生成系统诊断报告注意这些端点由系统内部使用或用于 Ollama 客户端兼容通常不由终端用户直接调用。OAuth 环境修复v3.6.1当某个 Provider 的 OAuth 环境变量缺失或损坏时可请求自动修复POST /api/system/env/repair Content-Type: application/json { provider: claude-code }成功响应示例{ 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 Transcription音频转写端点基于 Deepgram 或 AssemblyAIPOST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data请求示例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。Ollama 兼容面向使用 Ollama API 格式的客户端# 聊天端点Ollama 格式 POST /v1/api/chat # 模型列表Ollama 格式 GET /api/tags请求会在 Ollama 与内部格式之间自动转换。类似的英文完整版还提供了面向无法注入Authorization头的集成场景的tokenized VS Code / Headerless 别名/api/v1/vscode/{token}/models、/api/v1/vscode/{token}/chat/completions、/api/v1/vscode/{token}/responses、/api/v1/vscode/{token}/api/chat、/api/v1/vscode/{token}/api/tags它们复用与/v1/*相同的处理器、响应形状完全一致不过 URL 中的 token 可能出现在反向代理日志与浏览器历史中应视为兼容性选项而非默认认证方式。Telemetry按 Provider 聚合的延迟遥测p50/p95/p99# 获取延迟遥测汇总各 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 } } }Budget按 API Key 管理预算# 获取全部 API Key 的预算状态 GET /api/usage/budget # 设置或更新预算 POST /api/usage/budget Content-Type: application/json { keyId: key-123, limit: 50.00, period: monthly }英文完整版中该端点已演进为更细粒度的 schemasetBudgetSchemaapiKeyId必填dailyLimitUsd、weeklyLimitUsd、monthlyLimitUsd至少一个大于零可选warningThreshold0–1、resetIntervaldaily|weekly|monthly、resetTimeHH:MM。旧版{keyId, limit, period}形状会返回400 Bad Request——接入方需注意这一兼容性变更。Request Processing一次请求的完整处理链路如下客户端向/v1/*发送请求路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直接 Provider/模型或别名/Combo从本地数据库按账户可用性筛选选择凭据Chat 场景进入handleChatCore—— 格式检测、翻译、缓存检查、幂等检查Provider executor 发送上游请求响应转译为客户端格式chat或原样返回embeddings/images/audio记录用量与日志出错时按 Combo 规则执行故障转移fallback完整架构参考docs/architecture/ARCHITECTURE.md。对照源码第 5 步之前的「路由层」职责可在 src/app/api/v1/chat/completions/route.ts 中看到内容类型守卫、准入队列、提示注入防护、别名解析而handleChat的准入包装chatAdmission.withChatAdmission与handleChatCore的深度校验/缓存/压缩解析则位于 src/sse/handlers/chat.ts。英文完整版还强调启用压缩时第 6 步的 Provider 转译之前会先执行主动压缩lite、Caveman、RTK 或 stacked并额外记录压缩分析与请求日志每个步骤的语义缓存/签名缓存检查由handleChatCore完成。AuthenticationDashboard 路由/dashboard/*使用auth_tokenCookie登录使用已保存的密码哈希校验回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login切换/v1/*路由在REQUIRE_API_KEYtrue时可选要求 Bearer API Key管理面共有四类凭据族dashboard 会话、本地 CLI token、oma_live_…Access Token、manage-scoped API Key其与推理 Key 的区别详见 docs/guides/MANAGEMENT-AUTH.md。另需注意v3.8.0 起/api/v1/agents/tasks/*与冷却管理端点已改为强制要求管理级认证未认证调用将收到401 Unauthorized。本文档是 OmniRoute 公开 API 面的速查与深度参考/v1推理端点chat/embeddings/images/audio、模型列表、多协议兼容、Dedicated Provider Routes与/api管理端点Provider、Usage、Settings、Monitoring、Backup、Tunnels、CLI Tools、Resilience、Evals、Policies 等均已列出各端点实际入参校验与响应结构可进一步对照 docs/openapi.yaml 与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），仅供参考