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/OmniRoute本篇技术指南以 OmniRoute 官方 API 参考文档为核心骨架系统梳理其公开的/v1/*推理接口Chat Completions、Embeddings、图像生成、语音转写、完整的兼容端点矩阵、管理面 Dashboard API以及请求从进入网关到返回客户端的完整处理流程与认证模型。读完本文你将能够直接使用 curl 调用 OmniRoute 网关完成多模态推理掌握自定义请求头、语义缓存、幂等去重与预算控制等进阶用法并理解这些能力在源码中的落点对应路由位于 src/app/api/v1 下的各route.ts。Chat Completions核心对话端点对话补全是网关最核心的入口采用 OpenAI 兼容格式通过provider/model前缀选择上游供应商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其入口逻辑先做一次最热路径上的最小结构校验chatCompletionsRouteShapeSchema只断言 body 为对象、model为可空字符串、messages为数组随后把解析后的 body 交给 src/sse/handlers/chat.ts 中的handleChat做真正的深层校验与转发。注释明确指出深层校验故意保持宽松例如允许完全缺失的model后续通过input或 antigravity 解析以及developer等新角色确保不拒绝合法的扩展请求。自定义请求/响应头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响应为true表示本次请求被去重X-OmniRoute-Progress响应enabled表示进度跟踪已开启X-OmniRoute-Session-Id响应OmniRoute 实际使用的会话 IDNginx 提示如果依赖下划线请求头如x_session_id需在 Nginx 配置中开启underscores_in_headers on;。Embeddings文本向量化POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { model: nebius/Qwen/Qwen3-Embedding-8B, input: The food was delicious }可用供应商包括Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、OpenRouter、GitHub Models。模型 ID 统一采用provider/model目录形式。列出全部 embedding 模型GET /v1/embeddings实现上该路由位于 src/app/api/v1/embeddings/route.tsGET返回getSpecialtyModelsResponse过滤出的类型为embedding的模型目录POST则通过validateBody(v1EmbeddingsSchema, rawBody)schema 定义于 src/shared/validation/schemas.ts做 Zod 校验失败即返回400通过后调用 src/lib/embeddings/service.ts 的createEmbeddingResponse生成响应。值得注意的认证细节见 src/app/api/v1/embeddings/route.ts当REQUIRE_API_KEYfalse时无效的 key 会被忽略以便匿名访问与其它客户端 API 行为一致。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 }可用供应商OpenAIGPT 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 → Returns all chat, embedding, and image models combos in OpenAI format该接口以 OpenAI 格式一次性返回全部聊天、向量、图像模型以及组合combo路由。模型目录的组装逻辑位于 src/app/api/v1/models 目录下catalog.ts、modelById.ts、catalogOpenrouter.ts等文件协同完成去重、排序、供应商映射与付费模型过滤。Compatibility Endpoints协议兼容矩阵OmniRoute 的关键设计是一套网关多套协议下表为完整的兼容端点清单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也就是说Claude Code 可以用 Anthropic 协议直连Gemini SDK 可以走v1betaOllama 客户端可以无缝切换网关。/v1beta/models/{...path}目录式路由由 src/app/api/v1beta/models/[...path]/route.ts 承接目录位于 src/app/api/v1beta。专用供应商路由POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations当模型 ID 缺少供应商前缀时网关会自动补全若模型与指定供应商不匹配则返回400。对应路由实现位于 src/app/api/v1/providers/[provider]。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 } }缓存命中时响应头X-OmniRoute-Cache: HIT会标注另外可通过请求头X-OmniRoute-No-Cache: true实现单次请求级绕过。Dashboard Management管理面 API管理类路由/api/*公开的登录接口除外不接受普通推理 API key 授权需要使用管理会话或管理作用域的凭据详见 MANAGEMENT-AUTH.md。下表为完整端点矩阵。认证EndpointMethod说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT开关必须登录供应商管理EndpointMethod说明/api/providersGET/POST列出 / 创建供应商/api/providers/[id]GET/PUT/DELETE管理单个供应商/api/providers/[id]/testPOST测试供应商连接/api/providers/[id]/modelsGET列出供应商模型/api/providers/validatePOST校验供应商配置/api/provider-nodes*Various供应商节点管理/api/provider-modelsGET/POST/PATCH/DELETE自定义模型增改、显隐、删除OAuth 流程EndpointMethod说明/api/oauth/[provider]/[action]Various供应商专属 OAuth路由与配置EndpointMethod说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按供应商 类型返回全部模型/api/combos*Various组合combo管理/api/keys*VariousAPI key 管理/api/pricingGET模型定价用量与分析EndpointMethod说明/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET单连接用量设置EndpointMethod说明/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全局系统提示词监控EndpointMethod说明/api/sessionsGET活跃会话跟踪/api/rate-limitsGET每账户限流/api/monitoring/healthGET健康检查 供应商摘要catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空备份与导入导出EndpointMethod说明/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 完整备份云同步EndpointMethod说明/api/sync/cloudVarious云同步操作/api/sync/initializePOST初始化同步/api/cloud/*Various云管理隧道EndpointMethod说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI 工具EndpointMethod说明/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 智能体EndpointMethod说明/api/acp/agentsGET列出全部检测到的智能体内置 自定义及状态/api/acp/agentsPOST添加自定义智能体或刷新检测缓存/api/acp/agentsDELETE按id查询参数移除自定义智能体GET 响应包含agents[]id、name、binary、version、installed、protocol、isCustom与summarytotal、installed、notFound、builtIn、custom。弹性与限流EndpointMethod说明/api/resilienceGET/PATCH读取/更新请求队列、连接冷却、供应商熔断器与等待设置/api/resilience/resetPOST重置供应商熔断器/api/rate-limitsGET每账户限流状态/api/rate-limitGET全局限流配置评测、策略与合规EndpointMethod说明/api/evalsGET/POST列出评测套件 / 运行评测/api/policiesGET/POST/DELETE管理路由策略/api/compliance/audit-logGET合规审计日志最近 N 条v1betaGemini 兼容EndpointMethod说明/v1beta/modelsGET以 Gemini 格式列出模型/v1beta/models/{...path}POSTGeminigenerateContent端点这些端点镜像 Gemini 原生 API 格式服务于期望直接使用 Gemini SDK 兼容性的客户端。内部 / 系统 APIEndpointMethod说明/api/initGET应用初始化检查首次运行使用/api/tagsGETOllama 兼容模型标签/api/restartPOST优雅重启服务器/api/shutdownPOST优雅关闭服务器/api/system/env/repairPOST修复 OAuth 供应商环境变量/api/system-infoGET生成系统诊断报告注意这些端点供系统内部或 Ollama 客户端兼容使用通常不面向终端用户。OAuth 环境变量修复v3.6.1POST /api/system/env/repair Content-Type: application/json { provider: claude-code }修复指定供应商缺失或损坏的 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。注意示例中的端口20128是本地默认 API/Dashboard 端口实际以你的部署配置为准。Ollama CompatibilityOllama 协议兼容面向使用 Ollama API 格式的客户端# Chat endpoint (Ollama format) POST /v1/api/chat # Model listing (Ollama format) GET /api/tags请求会在 Ollama 格式与内部格式之间自动翻译。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 } } }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 设定月度等周期性的花费上限是网关配额感知路由的前置控制手段。Request Processing请求处理全链路一次/v1/*请求的完整生命周期如下客户端向/v1/*发送请求路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直接provider/model或别名 / combo从本地数据库选择凭据并按账户可用性过滤聊天请求进入handleChatCore——格式检测、翻译、缓存检查、幂等检查供应商执行器provider executor发送上游请求响应被翻译回客户端格式聊天或原样返回embeddings / images / audio记录用量与日志出错时按 combo 规则触发回退fallback。handleChat的实现在 src/sse/handlers/chat.ts聊天路由 src/app/api/v1/chat/completions/route.ts 通过admitChatRequest见 src/shared/middleware/chatBodyAdmission.ts执行准入排队并借助 src/middleware/promptInjectionGuard 做注入防护——这些都属于第 5 步请求进入核心处理前的实际守卫。更完整的架构说明见 ARCHITECTURE.md。Authentication认证模型Dashboard 路由/dashboard/*使用auth_tokencookie登录使用已保存的密码哈希校验回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login切换当REQUIRE_API_KEYtrue时/v1/*路由可选地要求 Bearer API key。结合前述源码可以总结出两层清晰的认证边界推理面/v1/*接受 Bearer API key且REQUIRE_API_KEYfalse时允许匿名访问管理面/api/*则必须持有管理会话或管理作用域凭据。这套设计让网关既能作为公网推理入口又能把仪表盘与管理操作隔离在独立授权域中。结语OmniRoute 的 API 面遵循OpenAI 格式为核心、多协议兼容为外围、管理 API 为纵深的三层结构日常推理只需学会/v1/chat/completions与自定义头Claude Code、Gemini SDK、Ollama 客户端可以通过协议兼容端点零改造接入而预算、缓存、限流、备份等运营能力全部沉淀在/api/*管理面。所有端点的最终实现都可以在 src/app/api/v1 的路由树中找到对应route.tsschema 校验集中在 src/shared/validation/schemas.ts如需机器可读的完整契约含更多细节可进一步查阅 docs/openapi.yaml。【免费下载链接】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），仅供参考
