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/*的调用契约、自定义头语义、语义缓存与幂等机制以及 Dashboard 管理与系统级端点。读完本文你将掌握如何用 OpenAI/Anthropic/Gemini/Ollama 兼容格式接入 OmniRoute、如何通过管理端点运维 Provider、密钥、用量、备份与弹性策略并能沿着源码调用链理解请求从路由到上游执行器的完整处理流程。目录Chat Completions核心对话补全接口Embeddings向量化接口Image Generation文生图接口List Models模型目录查询Compatibility Endpoints多协议兼容面Semantic Cache语义缓存与幂等Dashboard Management管理端接口全景Audio Transcription语音转写Ollama CompatibilityOllama 兼容Telemetry延迟遥测Budget密钥预算管理Request Processing请求处理链路Authentication认证模型Chat Completions核心对话补全接口聊天补全是 OmniRoute 使用频率最高的入口完全采用 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 }模型 ID 采用provider/model前缀形态如上例cc/...指向 Claude 系模型请求体支持完整的 OpenAI messages 结构与流式开关。从源码结构看该端点由 src/app/api/v1/chat/completions/route.ts 承接随后进入open-sse/handlers/chatCore.ts中的handleChatCore完成格式检测、翻译、缓存与幂等检查详见下文请求处理链路。自定义请求/响应头Header方向说明X-OmniRoute-No-CacheRequest设为true时绕过缓存X-OmniRoute-ProgressRequest设为true时启用进度事件X-Session-IdRequest粘性会话键用于外部会话亲和session affinityx_session_idRequest下划线变体同样接受直连 HTTP 场景Idempotency-KeyRequest去重键5 秒窗口X-Request-IdRequest备选去重键X-OmniRoute-CacheResponseHIT或MISS仅非流式响应X-OmniRoute-IdempotentResponse若响应被去重值为trueX-OmniRoute-ProgressResponse若进度追踪开启值为enabledX-OmniRoute-Session-IdResponseOmniRoute 实际生效的会话 IDNginx 注意事项若你依赖下划线请求头例如x_session_id需在 Nginx 配置中启用underscores_in_headers on;否则该头会被反向代理默认丢弃。Idempotency-Key/X-Request-Id对应的去重逻辑在源码中有明确落点handleChatCore在请求早期即调用checkIdempotencyCache见 open-sse/handlers/chatCore.ts命中后直接返回已缓存结果同时复用同一把幂等键在后续阶段落库保存保证 5 秒窗口内的重复请求不重复计费、不重复触发上游。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。模型 ID 遵循provider/model前缀例如nebius/Qwen/Qwen3-Embedding-8B即由 Nebius 承载 Qwen3-Embedding-8B。同时提供模型清单查询# List all embedding models GET /v1/embeddings底层实现对应open-sse/handlers/embeddings.ts中的handleEmbedding见 open-sse/handlers/embeddings.ts该处理器负责将统一入参翻译为各上游 Provider 的原始格式并把返回的向量原样回传给客户端嵌入场景不需要做面向客户端的格式回译。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同 GET 端点既承担单次生成的 POST 语义也承担列出可用文生图模型的目录语义。底层实现对应open-sse/handlers/imageGeneration.ts中的handleImageGeneration见 open-sse/handlers/imageGeneration.ts。List Models模型目录查询GET /v1/models Authorization: Bearer your-api-key → Returns all chat, embedding, and image models combos in OpenAI format该端点一次性返回全部聊天、嵌入、文生图模型以及组合combo输出为 OpenAI 兼容的模型目录格式。客户端可用它做模型选择器、自动补全或健康检查。Compatibility Endpoints多协议兼容面OmniRoute 在同一端口上同时暴露多套主流协议客户端无需改代码即可切换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也就是说同一套上游 Provider 资源既可以由 Claude Code / Anthropic SDK 通过/v1/messages调用也可以由 Gemini SDK 通过/v1beta调用还可以由 Ollama 客户端通过/v1/api/chat调用——OmniRoute 在内部完成格式互译。Dedicated Provider Routes定向 Provider 路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations若请求体中的模型 ID 缺少 provider 前缀系统会自动补上该路径中的{provider}前缀若模型与声明的 Provider 不匹配返回400。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 } }字段说明semanticCache.memorySize/memoryMaxSize语义缓存内存层当前条目数与上限示例中为 42/500semanticCache.dbSize落库缓存条目数示例为 128semanticCache.hitRate整体命中率示例 0.65idempotency.activeKeys幂等窗口中活跃的去重键数量idempotency.windowMs幂等窗口长度默认 5000 毫秒即 5 秒。在实现层面语义缓存与幂等去重分别在handleChatCore中以checkSemanticCache与checkIdempotencyCache两个独立入口执行见 open-sse/handlers/chatCore.ts前者负责语义相似命中后者负责请求级去重共同构成缓存省成本 幂等防重复的双保险。Dashboard Management管理端接口全景管理类路由/api/*公开的 auth/login 除外不由普通推理 API Key 授权需走管理认证Dashboard 会话 cookie、本地 CLI token、oma_live_…Access Token 或 manage-scope API Key。Authentication认证EndpointMethodDescription/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT切换是否要求登录Provider ManagementProvider 管理EndpointMethodDescription/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 FlowsEndpointMethodDescription/api/oauth/[provider]/[action]VariousProvider 专属 OAuth 流程Routing Config路由与配置EndpointMethodDescription/api/models/aliasGET/POST模型别名/api/models/catalogGET按 Provider 类型查看全部模型/api/combos*VariousCombo组合路由管理/api/keys*VariousAPI Key 管理/api/pricingGET模型定价Usage Analytics用量与分析EndpointMethodDescription/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET单连接用量Settings设置EndpointMethodDescription/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监控EndpointMethodDescription/api/sessionsGET活跃会话追踪/api/rate-limitsGET每账号速率限制/api/monitoring/healthGET健康检查 Provider 摘要catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空Backup Export/Import备份与导入导出EndpointMethodDescription/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云同步EndpointMethodDescription/api/sync/cloudVarious云同步操作/api/sync/initializePOST初始化同步/api/cloud/*Various云管理Tunnels隧道EndpointMethodDescription/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI ToolsEndpointMethodDescription/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 AgentsAgent 客户端协议代理EndpointMethodDescription/api/acp/agentsGET列出检测到的全部代理内置 自定义及状态/api/acp/agentsPOST添加自定义代理或刷新检测缓存/api/acp/agentsDELETE按id查询参数移除自定义代理GET 响应包含agents[]id、name、binary、version、installed、protocol、isCustom以及summarytotal、installed、notFound、builtIn、custom。Resilience Rate Limits弹性与速率限制EndpointMethodDescription/api/resilienceGET/PATCH读写请求队列、连接冷却、Provider 熔断器与等待设置/api/resilience/resetPOST重置 Provider 熔断器/api/rate-limitsGET每账号速率限制状态/api/rate-limitGET全局速率限制配置Evals评估EndpointMethodDescription/api/evalsGET/POST列出评估套件 / 运行评估Policies路由策略EndpointMethodDescription/api/policiesGET/POST/DELETE管理路由策略Compliance合规EndpointMethodDescription/api/compliance/audit-logGET合规审计日志最近 N 条v1betaGemini 兼容EndpointMethodDescription/v1beta/modelsGET以 Gemini 格式列出模型/v1beta/models/{...path}POSTGeminigenerateContent端点这些端点镜像 Gemini 的 API 形态供期望原生 Gemini SDK 兼容性的客户端使用。Internal / System APIs内部 / 系统接口EndpointMethodDescription/api/initGET应用初始化检查首次运行时使用/api/tagsGETOllama 兼容的模型标签供 Ollama 客户端/api/restartPOST触发优雅的服务重启/api/shutdownPOST触发优雅的服务关闭/api/system/env/repairPOST修复 OAuth Provider 环境变量/api/system-infoGET生成系统诊断报告注意上述端点由系统内部使用或用于 Ollama 客户端兼容通常不面向最终用户直接调用。OAuth Environment RepairOAuth 环境修复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表明修复前会先对原环境变量做备份属于可回滚的安全操作。Audio Transcription语音转写POST /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。底层实现为open-sse/handlers/audioTranscription.ts中的handleAudioTranscription见 open-sse/handlers/audioTranscription.ts负责 multipart 解析与上游 STT 服务的调用。Ollama CompatibilityOllama 兼容面向使用 Ollama API 形态的客户端# Chat endpoint (Ollama format) POST /v1/api/chat # Model listing (Ollama format) GET /api/tags请求会在 Ollama 格式与 OmniRoute 内部格式之间自动互译因此本机已配置好 Ollama 客户端的工具可以直接把 base URL 指向 OmniRoute 端口默认 20128。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 以分位数聚合上报延迟p50/p95/p99毫秒以及采样计数count可用于监控各上游的尾延迟分布。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 }请求体说明keyId目标 API Key 标识limit预算额度示例 50.00单位 USDperiod结算周期示例monthly。设置后即可为每个密钥设置独立预算上限超出即拒绝服务实现按密钥的用量治理。Request Processing请求处理链路OmniRoute 的请求处理遵循一条清晰的流水线文档中的标准 9 步流程客户端向/v1/*发送请求路由处理器分发到handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直连 provider/model或别名/combo 解析从本地数据库选择凭据并按账号可用性过滤聊天场景进入handleChatCore——格式检测、翻译、缓存检查、幂等检查Provider 执行器向上游发送请求响应回译为客户端格式聊天或原样返回嵌入/图像/音频记录用量与日志根据 combo 规则在出错时执行回退fallback。上述流程在源码中有完整印证路由层见 src/app/api/v1/route.ts 及src/app/api/v1/下的各子路由核心聊天逻辑handleChatCore位于 open-sse/handlers/chatCore.ts其中第 5 步的缓存检查即调用checkSemanticCache语义缓存与checkIdempotencyCache幂等去重嵌入、文生图、转写则分别对应open-sse/handlers/embeddings.ts、open-sse/handlers/imageGeneration.ts、open-sse/handlers/audioTranscription.ts中的同名处理器。此外仓库还提供独立的 OCR 处理器handleOcr见 open-sse/handlers/ocr.ts供文档识别类请求复用同一套路由 → 处理器 → 执行器 → 回译骨架。更完整的架构说明可阅读 docs/architecture/ARCHITECTURE.md。Authentication认证模型Dashboard 路由/dashboard/*使用auth_tokencookie 认证登录校验保存的密码哈希并回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login开关/v1/*路由在REQUIRE_API_KEYtrue时可选要求 Bearer API Key。由此形成两个清晰的认证域推理面/v1/*Bearer API Key与管理面/api/*Dashboard 会话或管理级密钥两者权限隔离推理密钥无法直接操作管理接口。小结从/v1/chat/completions到/api/system/env/repairOmniRoute 的 API 面覆盖了推理、多协议兼容、语义缓存、弹性治理、用量分析与系统运维的完整闭环。无论你是接入端开发者关注POST /v1/*的请求形态与自定义头、路由运维者关注/api/providers*、/api/resilience*还是平台治理者关注/api/keys*、/api/usage/*、/api/db-backups*都可以按本文的端点清单直接上手。若需更细粒度的契约定义可进一步查阅仓库根目录的 docs/openapi.yaml 机器可读规范以及 docs/architecture/ARCHITECTURE.md 中的完整架构参考。【免费下载链接】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），仅供参考