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/OmniRouteOmniRoute 是一个开源 MIT 许可的统一 AI 网关通过一个端点即可接入 352 家以上提供商其中 150 免费、1200 模型支持 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 等客户端。本文是 OmniRoute 官方 API 参考docs/i18n/fr/docs/reference/API_REFERENCE.md的完整中文技术解读聚焦于网关对外暴露的两大接口面面向 AI 客户端的公共/v1推理接口Chat Completions、Embeddings、Image Generation、音频转写等与面向运维者的/api管理接口提供商管理、用量分析、备份、隧洞、弹性治理等。读完本文你将掌握 OmniRoute 每个端点的调用方式、认证模型、自定义响应头语义以及请求在网关内部的完整处理链路与对应源码位置。目录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 }模型字段使用provider/model形式的提供商前缀 ID如cc/claude-opus-4-6、glm/glm-4.6。在 src/app/api/v1/chat/completions/route.ts 中可以看到该路由的入口处理先做Content-Type 守卫非application/json的请求体直接返回415 unsupported_media_typeRFC 7231 语义与 OpenAI/Anthropic 边界行为对齐通过admitChatRequestadmitChatStructure做入口接纳admission控制在 JSON 解析前按真实字节数预占重型容量避免缺失或虚报的Content-Length绕过限制请求体只json()解析一次随后交给handleChat实现在 src/sse/handlers/chat.ts做深层校验messages/model/temperature/top_p/max_tokens/n 等路由层仅保留一个刻意宽松的 shape schema.passthrough()避免在热路径上重复拒绝合法请求。自定义响应头请求与响应均可携带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;。英文原版docs/reference/API_REFERENCE.md进一步补充了响应侧遥测头法语版同样适用路由决策X-OmniRoute-Decision返回strategy名称; provider别名; latency_msn名称为组合路由策略名非组合请求则为single每次完成响应都会携带成本遥测非流式成功响应会附带X-OmniRoute-Response-CostUSD固定 10 位小数、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。这些头同样由/v1/responses、/v1/messages以及媒体端点/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/rerank、/v1/videos/generations、/v1/music/generations、/v1/moderations发出缓存命中语义语义缓存 HIT 时不发起上游调用因此X-OmniRoute-Response-Cost为0.0000000000命中服务的增量成本原始/应有成本单独通过X-OmniRoute-Cost-Saved上报。计费方应累加X-OmniRoute-Response-Cost缓存分析方应聚合X-OmniRoute-Cost-Saved。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形式如jina-ai/jina-embeddings-v5-omni-small。# 列出所有嵌入模型 GET /v1/embeddings从源码看src/app/api/v1/embeddings/route.ts该路由导入v1EmbeddingsSchema做 Zod 校验通过extractApiKey/isValidApiKey完成 Bearer 鉴权并以enforceApiKeyPolicy执行 API Key 策略最终交予handleEmbeddingopen-sse/handlers/embeddings.ts执行。英文原版还说明注册表声明支持多模态的模型可接受最多 32 个提供商中立的媒体条目text/image/audio/video/document内联 base64 媒体单条目上限 8 MiB、跨请求合计 16 MiBJina v5 Omni 系列的EmbeddingsV5Request原生文档会被原样转发到https://api.jina.ai/v1/embeddings。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本地。本地推理部署SD WebUI/ComfyUI可通过 OmniRoute 纳入统一的路由与自动故障转移体系。# 列出所有图像模型 GET /v1/images/generationsList Models模型列表GET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回所有聊天、嵌入、图像模型以及组合combo该端点由 src/app/api/v1/models/ 下的路由与目录构建模块catalog.ts、catalogRequest.ts、catalogResponse.ts、modelById.ts等支撑目录中既包含直连提供商模型也包含 OmniRoute 定义的组合路由combo模型。英文原版进一步说明了两个对客户端影响显著的细节模型前缀模式?prefix目录中大部分模型以提供商前缀发布可通过MODELS_CATALOG_PREFIX_MODE特性开关控制并支持按请求覆盖——prefixalias每模型一个短别名、prefixdual服务器默认同时输出cc/…与claude/…两种 ID目录规模约翻倍、prefixcanonical仅完整提供商前缀。无思考变体no-thinking支持思考的 Claude 模型会额外发布claude-3-omniroute-no-thinking/provider/model形式的变体 ID选择该 ID 会在/v1/messages路径上抑制推理thinking:{type:disabled}或在/v1/chat/completions路径上丢弃reasoning/reasoning_effort字段。Compatibility Endpoints兼容端点OmniRoute 不止暴露 OpenAI 格式还同时提供 Anthropic、Gemini、Ollama 等生态的兼容入口客户端可以“原格式进、原格式出”方法路径格式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专用提供商路由Dedicated Provider RoutesPOST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations当模型 ID 缺少提供商前缀时网关会自动补全若模型与路径中的提供商不匹配返回400。英文原版补充说明/v1/rerank、/v1/classify、/v1/segment、/v1/moderations、/v1/audio/speech、/v1/images/edits、/v1/videos/generations、/v1/music/generations等也遵循同样的Bearer Zod 校验模式schema 位于 src/shared/validation/schemas.ts。针对无法携带Authorization头的客户端还提供 URL 内嵌密钥的兼容写法?token、?apiKey、?api_key、?key以及/api/v1/vscode/{token}/...令牌化别名。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 } }语义缓存是 OmniRoute 降本的核心机制之一命中时直接在本地返回不发起上游调用因此X-OmniRoute-Response-Latency接近零。英文原版提醒延迟敏感客户端基准测试、p50/p99 监控应改用X-OmniRoute-Cache-Latency头判断值为synthetic表示响应来自缓存、并非真实上游耗时头缺失则表示真实上游调用。缓存绕行有两条路径按密钥创建/更新 API Key 时设置cacheDefaultMode: bypass跳过缓存查找、始终访问上游按请求任何请求携带X-OmniRoute-No-Cache: true即可绕过缓存与密钥设置无关。Dashboard Management管理接口管理路由/api/*公开登录除外不由普通推理 API Key 授权需使用管理认证Dashboard 会话、本地 CLI Token、oma_live_…Access Token 或带 manage 作用域的 API Key详见 docs/guides/MANAGEMENT-AUTH.md。下面按功能域列出全部管理端点。认证Authentication端点方法说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT开关“要求登录”提供商管理Provider Management端点方法说明/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 流程端点方法说明/api/oauth/[provider]/[action]Various提供商专属 OAuth路由与配置Routing Config端点方法说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按提供商类型列出全部模型/api/combos*Various组合combo管理/api/keys*VariousAPI 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健康检查 提供商汇总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/cloudVarious云同步操作/api/sync/initializePOST初始化同步/api/cloud/*Various云端管理隧洞Tunnels端点方法说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI 工具端点方法说明/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 AgentAgent Client Protocol端点方法说明/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读取/更新请求队列、连接冷却、提供商熔断与等待设置/api/resilience/resetPOST重置提供商熔断器/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 兼容性的客户端使用。内部 / 系统 APIInternal / System APIs端点方法说明/api/initGET应用初始化检查首次运行时使用/api/tagsGETOllama 兼容模型标签供 Ollama 客户端/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 }受支持模型 IDdeepgram/nova-3、assemblyai/best英文原版补充openai/whisper-1需 OpenAI Keyopenrouter/deepgram/nova-3走 OpenRouter Key裸deepgram/nova-3则不会经过 OpenRouter。受支持格式mp3、wav、m4a、flac、ogg、webm。实现层面该端点由 open-sse/handlers/audioTranscription.ts 中的handleAudioTranscription处理源码第 742 行路由位于 src/app/api/v1/audio/transcriptions/route.ts。Ollama CompatibilityOllama 兼容面向使用 Ollama API 格式的客户端# 聊天端点Ollama 格式 POST /v1/api/chat # 模型列表Ollama 格式 GET /api/tags请求会在 Ollama 格式与 OmniRoute 内部格式之间自动翻译因此 Ollama 生态的既有客户端无需改造即可接入 OmniRoute 的模型目录与路由能力。Telemetry遥测# 获取延迟遥测汇总每提供商的 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 } } }英文原版还补充了丰富的分析端点族/api/analytics/auto-routing自动路由统计调用总数、策略分布、层级分布、Top 提供商、/api/analytics/compression压缩统计节省 token、节省百分比、模式与引擎分布、/api/analytics/diversity基于香农熵的提供商多样性追踪防止单点故障。Budget预算# 获取所有 API Key 的预算状态 GET /api/usage/budget # 设置或更新预算 POST /api/usage/budget Content-Type: application/json { keyId: key-123, limit: 50.00, period: monthly }Schema 说明英文原版setBudgetSchemaapiKeyId必填dailyLimitUsd、weeklyLimitUsd、monthlyLimitUsd三者至少其一大于 0可选字段warningThreshold0–1、resetIntervaldaily/weekly/monthly、resetTimeHH:MM。旧的{keyId, limit, period}形状返回400 Bad Request。Request Processing请求处理链路法语版文档给出了一个清晰的九步处理流程客户端向/v1/*发送请求路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直连 provider/model或别名/组合从本地数据库选择凭据并过滤账号可用性聊天请求进入handleChatCore格式检测、翻译、缓存检查、幂等检查提供商执行器向远端发送请求响应翻译回客户端格式聊天或原样返回嵌入/图像/音频记录用量与日志出错时按组合combo规则执行故障转移这些函数在源码中均可逐一对应路由层POST /v1/chat/completions→ src/app/api/v1/chat/completions/route.ts最终调用 src/sse/handlers/chat.ts 的handleChat核心逻辑handleChatCore定义于 open-sse/handlers/chatCore.ts完成格式检测、翻译初始化、语义/签名缓存检查与组合压缩设置解析嵌入handleEmbedding定义于 open-sse/handlers/embeddings.ts图像handleImageGeneration定义于 open-sse/handlers/imageGeneration.ts音频转写handleAudioTranscription定义于 open-sse/handlers/audioTranscription.ts。英文原版在步骤 5–6 之间补充了两点handleChatCore同时检查语义/签名缓存并解析组合压缩设置启用压缩时lite、Caveman、RTK 或叠加会在提供商翻译之前执行主动压缩第 8 步除用量外还会记录压缩分析与请求日志。完整架构参考docs/architecture/ARCHITECTURE.md。Authentication认证Dashboard 路由/dashboard/*使用auth_tokenCookie登录校验已保存的密码哈希回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login切换/v1/*路由在REQUIRE_API_KEYtrue时可选要求 Bearer API Key。这里区分两个认证面/v1/*推理面使用普通 API KeyBearer/api/*管理面使用管理认证——Dashboard 会话、本地 CLI Token、oma_live_…Access Token 或带 manage 作用域的 API Key四类凭据家族的完整说明见 docs/guides/MANAGEMENT-AUTH.md。结语OmniRoute 的 API 面可以概括为“一套provider/model寻址体系 多协议兼容层 深度管理面”客户端侧无论是 OpenAI、Anthropic、Gemini 还是 Ollama 生态都能以原生格式接入同一个网关并借助自定义响应头获得缓存命中、路由决策与成本遥测等可观测信息运维侧从提供商/OAuth/Key 管理、用量分析、弹性治理到备份迁移全部具备 REST 管理端点。机器可读的完整契约见 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），仅供参考