OmniRoute API 参考指南从 /v1 推理端点、兼容接口到管理后台的完整调用手册【免费下载链接】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/OmniRouteOmniRoute 是一个免费开源的 MIT 协议 AI 网关一个端点接入 352 个 Provider、1200 模型含 150 免费模型支持 Claude Code、Codex、Cursor、OpenCode、Cline 与 Copilot 等主流客户端。本文以仓库内的 API Reference印地语版与英文原版 docs/reference/API_REFERENCE.md 内容对应为骨架系统整理公开的/v1推理接口、OpenAI/Anthropic/Gemini/Ollama 多协议兼容层、语义缓存、Dashboard 管理端点以及请求处理与鉴权机制。读者读完后可以掌握每个端点的请求格式、参数含义、鉴权方式与底层实现并能够在 Claude Code、Codex、VS Code 等客户端中直接对接使用。目录Chat Completions 对话补全Embeddings 向量嵌入Image Generation 图像生成List Models 模型列表Compatibility Endpoints 协议兼容层Semantic Cache 语义缓存Dashboard Management 管理与运维端点Audio Transcription 音频转写Ollama Compatibility Ollama 兼容Telemetry 延迟遥测Budget 预算Request Processing 请求处理流程Authentication 鉴权Chat Completions 对话补全对话补全是 OmniRoute 的核心推理接口采用 OpenAI 兼容的请求格式默认服务端口为20128见 docs/architecture/ARCHITECTURE.md 中的PORT20128配置。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表示通过 Claude Code 账号路由到 Claude Opus 4.6stream: true开启 SSE 流式输出。从源码看该路由的实现在 src/app/api/v1/chat/completions/route.ts入口先做单例初始化translator 只会初始化一次随后对请求体做一次“最热路径”的最小化校验仅断言model为可空字符串、messages为数组真正的深度校验交给更下层的handleChat见 src/sse/handlers/chat.ts。这样设计是为了在保持高吞吐的同时把完整字段校验、模型解析、配额判断等逻辑收敛到统一处理链路中。Custom Headers 自定义请求头Header方向说明X-OmniRoute-No-CacheRequest设为true时绕过缓存X-OmniRoute-ProgressRequest设为true时启用进度事件X-Session-IdRequest外部会话亲和性sticky session的会话键x_session_idRequest下划线变体同样被接受直连 HTTP 时Idempotency-KeyRequest去重键5 秒窗口X-Request-IdRequest备选去重键X-OmniRoute-CacheResponseHIT或MISS非流式响应X-OmniRoute-IdempotentResponse为true表示本次请求已被去重X-OmniRoute-ProgressResponse为enabled表示已开启进度跟踪X-OmniRoute-Session-IdResponseOmniRoute 实际使用的会话 IDNginx 注意事项如果你依赖下划线请求头例如x_session_id需要在 Nginx 中开启underscores_in_headers on;否则下划线头会被 Nginx 默认丢弃。从实现看这些请求头在 open-sse/handlers/chatCore/headers.ts 中统一解析如getHeaderValueCaseInsensitive、isNoMemoryRequested、resolveCompressionHeader支持大小写不敏感读取会话 ID 的解析与准入队列逻辑位于 src/shared/middleware/chatBodyAdmission.tsresolveSessionId、admitChatRequest等。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、Jina AI。目录中的模型 ID 统一采用provider/model形式例如nebius/Qwen/Qwen3-Embedding-8B。列出所有嵌入模型GET /v1/embeddings路由实现在 src/app/api/v1/embeddings/route.ts处理函数为handleEmbedding。嵌入类接口的响应不做格式翻译直接以上游 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本地。列出所有图像模型GET /v1/images/generationsList Models 模型列表GET /v1/models Authorization: Bearer your-api-key → 返回所有对话、嵌入、图像模型 Combo组合路由的 OpenAI 格式列表该接口返回完整的模型目录客户端模型选择器、CLI 配置可据此渲染候选模型。Compatibility Endpoints 协议兼容层OmniRoute 的核心卖点是“一个端点、多协议兼容”——同一套后端路由同时以 OpenAI、Anthropic、Gemini、Ollama 等格式对外服务MethodPath格式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其中/v1beta/*端点完全镜像 Gemini 的 API 格式供期望原生 Gemini SDK 兼容性的客户端使用/v1/api/chat与GET /api/tags则面向 Ollama 客户端请求会在 Ollama 与内部格式之间自动翻译。Dedicated Provider Routes 直连路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations直连路由用于显式指定 Provider。provider前缀在模型 ID 缺失时会自动补全如果模型与路由指定的 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 } }semanticCache部分给出语义缓存的当前内存条目数、内存上限、数据库条目数与命中率idempotency部分给出当前活跃去重键数量与去重窗口默认 5000ms即 5 秒。从实现看语义缓存命中检查checkSemanticCache与幂等缓存检查checkIdempotencyCache都在 open-sse/handlers/chatCore.ts 的handleChatCore阶段执行属于“格式化检测 → 翻译 → 缓存检查 → 幂等检查”流水线的一部分。缓存命中时响应头会返回X-OmniRoute-Cache: HIT任何请求都可以通过X-OmniRoute-No-Cache: true请求头按请求粒度绕过缓存。Dashboard Management 管理与运维端点管理类路由/api/*公开的auth/login除外不接受普通推理 API Key 的授权必须使用管理凭据Dashboard 会话、本地 CLI Token、oma_live_…Access Token 或 manage-scoped API Key详见 docs/guides/MANAGEMENT-AUTH.md。Authentication 认证端点Method说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT切换是否强制登录Provider Management 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 Flows OAuth 流程端点Method说明/api/oauth/[provider]/[action]VariousProvider 专属 OAuthRouting Config 路由与配置端点Method说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按 Provider 类型列出全部模型/api/combos*VariousCombo组合路由管理/api/keys*VariousAPI Key 管理/api/pricingGET模型定价Usage Analytics 用量与分析端点Method说明/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET单连接用量Settings 设置端点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全局系统提示词Monitoring 监控端点Method说明/api/sessionsGET活跃会话跟踪/api/rate-limitsGET每账号速率限制/api/monitoring/healthGET健康检查 Provider 汇总catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空Backup Export/Import 备份与导入导出端点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 归档Cloud Sync 云同步端点Method说明/api/sync/cloudVarious云同步操作/api/sync/initializePOST初始化同步/api/cloud/*Various云管理Tunnels 隧道端点Method说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 使用/api/tunnels/cloudflaredPOST启用/禁用 Cloudflare Quick Tunnelactionenable/disableCLI Tools CLI 工具状态端点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 ACP 代理端点Method说明/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 弹性与速率限制端点Method说明/api/resilienceGET/PATCH读取/更新请求队列、连接冷却、Provider 熔断与等待设置/api/resilience/resetPOST重置 Provider 熔断器/api/rate-limitsGET每账号速率限制状态/api/rate-limitGET全局速率限制配置Evals 评估端点Method说明/api/evalsGET/POST列出评估套件 / 运行评估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 兼容性的客户端使用。Internal / System APIs 内部与系统 API端点Method说明/api/initGET应用初始化检查首次运行使用/api/tagsGETOllama 兼容的模型标签供 Ollama 客户端/api/restartPOST触发优雅重启/api/shutdownPOST触发优雅关机/api/system/env/repairPOST修复 OAuth Provider 环境变量/api/system-infoGET生成系统诊断报告注意这些端点供系统内部或 Ollama 客户端兼容使用通常不应由终端用户直接调用。OAuth Environment Repair 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 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 }支持的模型deepgram/nova-3、assemblyai/best。支持的格式mp3、wav、m4a、flac、ogg、webm。Ollama Compatibility Ollama 兼容对于使用 Ollama API 格式的客户端# 对话端点Ollama 格式 POST /v1/api/chat # 模型列表Ollama 格式 GET /api/tags请求会在 Ollama 与内部格式之间自动翻译因此 Ollama 生态的工具可以直接以 OmniRoute 为后端。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 } } }Budget 预算# 获取所有 API Key 的预算状态 GET /api/usage/budget # 设置或更新预算 POST /api/usage/budget Content-Type: application/json { keyId: key-123, limit: 50.00, period: monthly }Request Processing 请求处理流程OmniRoute 的/v1/*请求按以下流水线处理客户端向/v1/*发送请求路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直接 provider/model或别名 / Combo从本地数据库选择凭据并按账号可用性过滤对话请求进入handleChatCore—— 格式检测、翻译、缓存检查、幂等检查Provider executor 向上游发送请求响应翻译回客户端格式对话嵌入/图像/音频则原样返回记录用量与日志出错时按 Combo 规则应用回退fallback。完整架构参考docs/architecture/ARCHITECTURE.md。从源码结构看handleChat位于 src/sse/handlers/chat.ts而handleChatCore拆分在 open-sse/handlers/chatCore.ts 及其chatCore/子目录中语义缓存semanticCache.ts、幂等idempotency.ts、请求头解析headers.ts、流式管线streamingPipeline.ts等路由层只做最轻量的形状校验与初始化体现了“薄路由 厚处理”的架构取舍。Authentication 鉴权Dashboard 路由/dashboard/*使用auth_tokencookie登录使用已保存的密码哈希回退到INITIAL_PASSWORD环境变量requireLogin可通过/api/settings/require-login切换/v1/*路由在REQUIRE_API_KEYtrue时可选要求 Bearer API Key。管理面Dashboard、/api/*管理端点与推理面/v1/*是两套独立的凭据体系普通推理 Key 只能调用/v1/*管理操作需要 Dashboard 会话或管理级凭据。这一隔离设计保证了网关在暴露给各类客户端使用的同时管理配置不被未授权访问具体凭据家族定义见 docs/guides/MANAGEMENT-AUTH.md。进一步阅读机器可读的完整 OpenAPI 规范docs/openapi.yaml管理鉴权四种凭据家族指南docs/guides/MANAGEMENT-AUTH.md系统架构与部署形态docs/architecture/ARCHITECTURE.md推理预算thinking budget配置docs/guides/THINKING_BUDGET.mdProvider 与模型参考docs/reference/PROVIDER_REFERENCE.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），仅供参考