企业官网建设流程全解析

OmniRoute API 参考详解：从 Chat Completions 到管理端点的完整接口体系与请求处理链路

【免费下载链接】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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

本篇以 OmniRoute 仓库中的 API 参考文档为主线，完整梳理其全部对外接口：OpenAI/Anthropic/Gemini/Ollama 兼容端点、嵌入与图像生成、语义缓存、Dashboard 管理面（Provider、密钥、预算、隧道、备份）、遥测与请求处理流水线。读完你可以直接基于文档中的端点表、请求示例和响应结构对接 OmniRoute，并借助仓库源码验证每个关键机制（缓存键生成、幂等去重、会话亲和、鉴权策略）的真实实现。

一、端点总览

OmniRoute 的 API 面可以分成两大类：

• /v1/*与/v1beta/*：面向 LLM 客户端的数据面（chat、embeddings、images、responses、messages 等），对应路由位于 src/app/api/v1/ 与 src/app/api/v1beta/ 下；
• /api/*：面向 Dashboard 与管理场景的控制面（Provider 管理、密钥、用量、设置、备份、隧道、遥测等），对应路由位于 src/app/api/ 下。

请求处理总流程（文档定义）：

1. 客户端向/v1/*发送请求；
2. 路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration；
3. 解析模型（直接 provider/model 或别名/combo）；
4. 从本地数据库选择凭据，并按账户可用性过滤；
5. chat 场景进入handleChatCore——格式检测、翻译、缓存检查、幂等检查；
6. Provider executor 向上游发送请求；
7. 响应翻译回客户端格式（chat），或原样返回（embeddings/images/audio）；
8. 记录用量与日志；
9. 出错时按 combo 规则应用 fallback。

完整架构参考见 docs/architecture/ARCHITECTURE.md。

二、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 }

自定义 Headers

Nginx 提示：如果依赖下划线头（如x_session_id），需开启underscores_in_headers on;。

源码级验证

上述头部机制在 src/app/api/v1/chat/completions/route.ts 中有直接印证：

• 会话亲和：路由在入口处调用resolveSessionId(request)与admitChatRequest(request, { sessionId, queueMs: CHAT_ADMISSION_QUEUE_MAX_MS })（来自@/shared/middleware/chatBodyAdmission）。这意味着X-Session-Id不仅决定粘性路由，还参与准入（admission）排队控制，队列超过上限的请求会直接被拒而不是拖垮进程。
• Content-Type 守卫：对非application/json的 POST body 直接返回415（unsupported_media_type），与 OpenAI/Anthropic 边缘行为保持一致，防止text/plainbody 悄悄进入 provider 解析流程。
• 宽松的前置 schema：路由只断言"非 null 对象、model若存在须为可空字符串、messages若存在须为数组"（zod.passthrough()），把真正的深度校验（temperature/top_p/max_tokens/n 等）下沉给handleChat，以避免在热路径上新增拒绝行为。
• 注入防护：路由持有一个单例createInjectionGuard，提示注入检测在handleChat内与 pino logger 一并重评估，避免重复打日志。

三、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。

列出全部嵌入模型：

GET /v1/embeddings

源码印证（src/app/api/v1/embeddings/route.ts）：

• GET /v1/embeddings通过getSpecialtyModelsResponse过滤model.type === "embedding"的目录条目，即文档所说的"列出全部嵌入模型"；
• POST先用v1EmbeddingsSchema做 body 校验，失败返回 400；
• 鉴权遵循REQUIRE_API_KEY特性开关：关闭时忽略非法 key 以保证匿名访问可用；开启时先校验 key 有效性（401），再调用enforceApiKeyPolicy强制模型访问限制与预算上限——这是 API key 策略在数据面上的落点。

四、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" }

支持的 Provider：OpenAI（GPT Image 2）、xAI（Grok Image）、Together AI（FLUX）、Fireworks AI、Nebius（FLUX）、Hyperbolic、NanoBanana、OpenRouter、SD WebUI（本地）、ComfyUI（本地）。

列出全部图像模型：

GET /v1/images/generations

五、List Models

GET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回全部 chat、embedding、image 模型 + combos

路由实现在 src/app/api/v1/models/，目录构建拆分为 catalog 分页、去重、OpenRouter 映射、付费过滤、视觉能力标注等模块，最终按 OpenAI/v1/models格式输出，因此标准 OpenAI 客户端可以零改造地列出 OmniRoute 中的全部可用模型（含 combo）。

六、兼容端点（Compatibility Endpoints）

指定 Provider 直连路由

POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations

若模型名缺少 provider 前缀会自动补全；模型与 provider 不匹配时返回400。这组路由在 src/app/api/v1/providers/[provider]/ 下实现，为绕过路由表直接打到指定上游的客户端提供了稳定入口。

七、语义缓存（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/lib/semanticCache.ts）

文件头注释完整定义了缓存语义，可与文档互相印证：

• 两级结构：内存 LRU（快路径）+ SQLite（跨重启持久化）；
• 缓存键：SHA-256(model + 归一化 messages + temperature + top_p)，且只对temperature=0的响应缓存；
• 流式兼容：流式响应在组装完成后入缓存，命中时一律返回 JSON；
• 绕过方式：请求头X-OmniRoute-No-Cache: true；
• 持久指标：cache_metrics表维护hits/misses/tokens_saved三个计数器，/api/cache/stats的hitRate即由此得出。

管理端点 src/app/api/cache/stats/route.ts 对 GET/DELETE 均先执行isAuthenticated鉴权（未认证返回 401），DELETE 成功后返回{ "success": true, "message": "Cache cleared" }。

八、Dashboard 与管理端点

认证

Provider 管理

OAuth 流程

路由与配置

用量与分析

设置

监控

备份与导出/导入

云同步

隧道

CLI 工具

CLI 响应包含字段：installed、runnable、command、commandPath、runtimeMode、reason。

ACP Agents

GET 响应包含agents[]（id、name、binary、version、installed、protocol、isCustom）与summary（total、installed、notFound、builtIn、custom）。

弹性与速率限制

Evals

策略（Policies）

合规（Compliance）

v1beta（Gemini 兼容）

这些端点镜像 Gemini 的 API 格式，供期望原生 Gemini SDK 兼容性的客户端使用。

内部 / 系统 API

注意：这些端点供系统内部或 Ollama 客户端兼容使用，终端用户通常不会直接调用。

OAuth 环境变量修复（v3.6.1+）

POST /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 "file=@recording.mp3" \ -F "model=deepgram/nova-3"

响应：

{ "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 }

支持的 Provider：deepgram/nova-3、assemblyai/best。

支持的格式：mp3、wav、m4a、flac、ogg、webm。

路由实现在 src/app/api/v1/audio/transcriptions/route.ts，由handleAudioTranscription处理。

十、Ollama 兼容

面向使用 Ollama API 格式（如ollamaCLI、Open WebUI 等）的客户端：

# 对话端点（Ollama 格式） POST /v1/api/chat # 模型列表（Ollama 格式） GET /api/tags

请求会在 Ollama 格式与内部格式之间自动转译，无需客户端做任何适配。

十一、遥测（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 } } }

该端点为路由决策与容量规划提供了按 Provider 分位的延迟基线。

十二、预算（Budget）

# 获取所有 API key 的预算状态 GET /api/usage/budget # 设置或更新预算 POST /api/usage/budget Content-Type: application/json { "keyId": "key-123", "limit": 50.00, "period": "monthly" }

预算是 API key 策略的一部分：如第三节源码所示，/v1/*数据面每次请求都会经enforceApiKeyPolicy校验模型访问限制与预算上限，超限时直接拒绝，因此预算约束在网关层即时生效，而不是事后统计。

十三、鉴权模型（Authentication）

文档定义的鉴权规则：

• Dashboard 路由（/dashboard/*）使用auth_tokencookie；
• 登录使用已保存的密码哈希；回退到INITIAL_PASSWORD；
• requireLogin可通过/api/settings/require-login切换；
• /v1/*路由在REQUIRE_API_KEY=true时要求 Bearer API key。

源码印证：

• src/app/api/v1/embeddings/route.ts 中isRequireApiKeyEnabled()为假时匿名可用、为真时缺失/无效 key 均返回 401，且注释明确说明该行为在"所有客户端 API"间保持一致；
• 管理面端点（如 src/app/api/cache/stats/route.ts）统一先过isAuthenticated，未认证返回 401；
• 缓存/统计类只读端点也受同一鉴权约束，避免敏感运营数据裸奔。

十四、总结

OmniRoute 的 API 参考覆盖了三条主线：

1. 数据面：以 OpenAI 格式为核心（/v1/chat/completions、/v1/embeddings、/v1/images/generations、/v1/models），叠加 Anthropic/v1/messages、OpenAI Responses、Gemini/v1beta、Ollama/v1/api/chat的格式兼容层，并通过/v1/providers/{provider}/*提供指定上游直连；
2. 增强机制：语义缓存（X-OmniRoute-Cache: HIT/MISS+/api/cache/stats）、幂等去重（Idempotency-Key，5s 窗口）、会话亲和（X-Session-Id）、进度事件（X-OmniRoute-Progress）；
3. 控制面：从 Provider/密钥/预算到备份、隧道、遥测、系统重启的完整管理端点集，全部纳入 Dashboard 鉴权体系。

结合仓库源码（src/app/api/v1/、src/lib/semanticCache.ts、src/app/api/cache/stats/route.ts）可以确认：文档中描述的头部语义、鉴权开关与缓存键规则均有对应的实现代码与持久化指标支撑，可作为对接与排障的可靠依据。

【免费下载链接】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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute