企业官网建设流程全解析

OmniRoute API 全端点参考：从 /v1 推理接口到管理面 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

本文以 OmniRoute 仓库的 API Reference 文档为核心，系统梳理其对外暴露的两层 API 体系：面向推理客户端的 OpenAI 兼容/v1/*端点（Chat、Embeddings、图像生成、音频转录、Ollama/Gemini 兼容层），以及面向运维与集成的/api/*管理端点（Provider 管理、密钥、用量、弹性控制、备份等）。读完本文，你可以直接复制请求示例接入任意 LLM 客户端，并借助X-OmniRoute-*响应头、语义缓存与幂等机制完成成本归因与去重，同时掌握完整的管理面 API 清单及其源码落点。

1. 两层 API 体系总览

OmniRoute 的 API 面可分为两层，这一划分在路由目录结构中可以直接印证：

• 推理层/v1/*：OpenAI 兼容及多协议兼容的推理端点，使用Authorization: Bearer <api-key>鉴权。对应路由树 src/app/api/v1/，包含chat/、embeddings/、images/、audio/、models/、ocr/等子目录。
• 管理层/api/*：Dashboard 与控制台使用的管理端点（Provider、密钥、用量、弹性、备份、隧道等），对应 src/app/api/ 下近百个功能目录。

机器可读的完整 OpenAPI 定义位于 docs/openapi.yaml，路由树的实际实现则以上述两个目录为准。

2. Chat Completions

2.1 基础请求

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 Code 渠道），也支持别名与 combo 解析。

2.2 自定义请求/响应头

Nginx 注意：如果你依赖下划线头（例如x_session_id），需要开启underscores_in_headers on;。

源码印证：响应头的命名常量集中在 src/shared/constants/headers.ts，其中除上述头外还定义了X-OmniRoute-Cache-Hit、X-OmniRoute-Cache-Latency、X-OmniRoute-Compression、X-OmniRoute-Cost-Saved、X-OmniRoute-Decision、X-OmniRoute-Response-Cost、X-OmniRoute-Tokens-In/Out、X-OmniRoute-Latency-Ms等成本遥测头。会话头的写入逻辑可参考 src/sse/handlers/chatHelpers.ts（X-OmniRoute-Session-Id的 set 调用）。幂等去重窗口（windowMs: 5000）由 src/lib/idempotencyLayer.ts 实现，语义缓存统计由 src/lib/semanticCache.ts 维护。

2.3 请求处理管线

从源码结构看，POST /v1/chat/completions的处理链路在 src/app/api/v1/chat/completions/route.ts 中清晰可见：路由层先做 CORS 预检、Content-Type 守卫（非 JSON 请求体按 RFC 7231 返回 415）、基于resolveSessionId的会话解析与admitChatRequest准入队列（容量预留 + 字节硬限），再经过一次宽松的形状校验（真正的深度校验由handleChat负责），最后委托给handleChat。完整的处理流程如下：

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 规则触发回退。

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

3. 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。

# 列出所有 embedding 模型 GET /v1/embeddings

实现位于 src/app/api/v1/embeddings/，同样受REQUIRE_API_KEY开关约束（见第 10 节鉴权）。

4. 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

5. List Models

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

模型 ID 普遍采用provider/model前缀。GET /v1/models支持?prefix=查询参数控制前缀模式（dual/alias/canonical），客户端模型选择器建议请求?prefix=alias以获得每模型单条目的干净列表。

6. 兼容端点（Compatibility Endpoints）

OmniRoute 的一个核心定位是"一个端点、多种协议"。下表列出各协议兼容端点：

这些端点分别落在 src/app/api/v1/ 下的messages/、responses/、embeddings/、images/、models/、api/（Ollama）以及 src/app/api/v1beta/ 目录中。

6.1 专用 Provider 路由

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

当请求体中模型缺少 provider 前缀时，系统会自动补上；模型与 provider 前缀不匹配时返回400。

6.2 Ollama 兼容

面向使用 Ollama API 格式（如 Ollama 客户端、api/chat协议）的请求：

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

请求会在 Ollama 格式与内部格式之间自动转换；/api/tags返回 Ollama 兼容的模型 tags，供 Ollama 客户端发现模型。

7. 音频转录（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。

8. 语义缓存（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 } }

其中idempotency.windowMs: 5000与第 2.2 节Idempotency-Key头的 5 秒去重窗口一致，可在 src/lib/idempotencyLayer.ts 中查看窗口实现；semanticCache各计数字段来自 src/lib/semanticCache.ts 的内存 + 数据库双层结构。

缓存命中时响应头X-OmniRoute-Cache标记HIT/MISS；请求方可用X-OmniRoute-No-Cache: true或 API key 级别的cacheDefaultMode: "bypass"跳过缓存读取。

9. Dashboard 与管理端点

管理面（/api/*）覆盖以下功能域。以下各表完整继承自 API Reference 文档，对应实现分散在 src/app/api/ 各子目录中。

9.1 认证（Authentication）

9.2 Provider 管理

9.3 OAuth 流程

9.4 路由与配置

9.5 用量与分析

9.6 设置（Settings）

9.7 监控（Monitoring）

9.8 备份与导入/导出

9.9 云同步（Cloud Sync）

9.10 隧道（Tunnels）

9.11 CLI 工具状态

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

9.12 ACP Agents

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

9.13 弹性与限流（Resilience & Rate Limits）

9.14 Evals 与 Policies

9.15 合规（Compliance）

9.16 v1beta（Gemini 兼容）

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

9.17 内部 / 系统 API

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

9.18 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" }

修复前会将现有环境变量备份到~/.omniroute/backups/下的.bak文件，保证可回滚。

10. 遥测、预算与鉴权

10.1 延迟遥测（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 } } }

10.2 预算（Budget）

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

10.3 鉴权模型（Authentication）

• Dashboard 路由（/dashboard/*）使用auth_tokencookie；
• 登录使用保存的密码哈希，回退到INITIAL_PASSWORD环境变量；
• 是否强制登录可通过/api/settings/require-login切换；
• /v1/*路由在REQUIRE_API_KEY=true时可选地要求 Bearer API key（该开关在 src/app/api/v1/embeddings/route.ts 等 v1 路由中被读取；未开启时匿名请求也可通过，适合本地开发场景）。

11. 快速接入清单

1. 启动 OmniRoute 服务（默认端口 20128，参考 docs/getting-started/QUICK-START.md）；
2. 在 Dashboard 创建 API key，或以REQUIRE_API_KEY=false本地运行；
3. 客户端按 OpenAI SDK 约定设置base_url为http://localhost:20128/v1，模型使用provider/model前缀；
4. 用GET /v1/models发现可用模型，用GET /api/monitoring/health检查 Provider 健康，用GET /api/cache/stats观察缓存命中率；
5. 通过X-OmniRoute-*响应头做成本与路由决策归因（X-OmniRoute-Decision会给出strategy/provider/latency_ms三元组）。

本文所有端点行为均可在 docs/openapi.yaml 的机器可读定义与src/app/api/、src/app/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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute