OmniRoute API 参考指南：从 /v1 推理端点、兼容接口到管理后台的完整调用手册

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

OmniRoute 是一个免费开源的 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 中的PORT=20128配置）。

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.6；stream: 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-Cache	Request	设为true时绕过缓存
X-OmniRoute-Progress	Request	设为true时启用进度事件
X-Session-Id	Request	外部会话亲和性（sticky session）的会话键
x_session_id	Request	下划线变体同样被接受（直连 HTTP 时）
Idempotency-Key	Request	去重键（5 秒窗口）
X-Request-Id	Request	备选去重键
X-OmniRoute-Cache	Response	HIT或MISS（非流式响应）
X-OmniRoute-Idempotent	Response	为true表示本次请求已被去重
X-OmniRoute-Progress	Response	为enabled表示已开启进度跟踪
X-OmniRoute-Session-Id	Response	OmniRoute 实际使用的会话 ID

Nginx 注意事项：如果你依赖下划线请求头（例如x_session_id），需要在 Nginx 中开启underscores_in_headers on;，否则下划线头会被 Nginx 默认丢弃。

从实现看，这些请求头在 open-sse/handlers/chatCore/headers.ts 中统一解析（如getHeaderValueCaseInsensitive、isNoMemoryRequested、resolveCompressionHeader），支持大小写不敏感读取；会话 ID 的解析与准入队列逻辑位于 src/shared/middleware/chatBodyAdmission.ts（resolveSessionId、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" }

可用 Provider：Nebius、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" }

可用 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 → 返回所有对话、嵌入、图像模型 + Combo（组合路由）的 OpenAI 格式列表

该接口返回完整的模型目录，客户端（模型选择器、CLI 配置）可据此渲染候选模型。

---

Compatibility Endpoints 协议兼容层

OmniRoute 的核心卖点是“一个端点、多协议兼容”——同一套后端路由同时以 OpenAI、Anthropic、Gemini、Ollama 等格式对外服务：

Method	Path	格式
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama

其中/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/login	POST	登录
/api/auth/logout	POST	登出
/api/settings/require-login	GET/PUT	切换是否强制登录

Provider Management Provider 管理

端点	Method	说明
/api/providers	GET/POST	列出 / 创建 Provider
/api/providers/[id]	GET/PUT/DELETE	管理单个 Provider
/api/providers/[id]/test	POST	测试 Provider 连接
/api/providers/[id]/models	GET	列出 Provider 模型
/api/providers/validate	POST	校验 Provider 配置
/api/provider-nodes*	Various	Provider 节点管理
/api/provider-models	GET/POST/PATCH/DELETE	自定义模型（新增、更新、隐藏/显示、删除）

OAuth Flows OAuth 流程

端点	Method	说明
/api/oauth/[provider]/[action]	Various	Provider 专属 OAuth

Routing & Config 路由与配置

端点	Method	说明
/api/models/alias	GET/POST	模型别名
/api/models/catalog	GET	按 Provider + 类型列出全部模型
/api/combos*	Various	Combo（组合路由）管理
/api/keys*	Various	API Key 管理
/api/pricing	GET	模型定价

Usage & Analytics 用量与分析

端点	Method	说明
/api/usage/history	GET	用量历史
/api/usage/logs	GET	用量日志
/api/usage/request-logs	GET	请求级日志
/api/usage/[connectionId]	GET	单连接用量

Settings 设置

端点	Method	说明
/api/settings	GET/PUT/PATCH	通用设置
/api/settings/proxy	GET/PUT	网络代理配置
/api/settings/proxy/test	POST	测试代理连接
/api/settings/ip-filter	GET/PUT	IP 白名单/黑名单
/api/settings/thinking-budget	GET/PUT	推理 Token 预算
/api/settings/system-prompt	GET/PUT	全局系统提示词

Monitoring 监控

端点	Method	说明
/api/sessions	GET	活跃会话跟踪
/api/rate-limits	GET	每账号速率限制
/api/monitoring/health	GET	健康检查 + Provider 汇总（catalogCount、configuredCount、activeCount、monitoredCount）
/api/cache/stats	GET/DELETE	缓存统计 / 清空

Backup & Export/Import 备份与导入导出

端点	Method	说明
/api/db-backups	GET	列出可用备份
/api/db-backups	PUT	创建手动备份
/api/db-backups	POST	从指定备份恢复
/api/db-backups/export	GET	下载数据库（.sqlite 文件）
/api/db-backups/import	POST	上传 .sqlite 文件替换数据库
/api/db-backups/exportAll	GET	下载完整备份（.tar.gz 归档）

Cloud Sync 云同步

端点	Method	说明
/api/sync/cloud	Various	云同步操作
/api/sync/initialize	POST	初始化同步
/api/cloud/*	Various	云管理

Tunnels 隧道

端点	Method	说明
/api/tunnels/cloudflared	GET	读取 Cloudflare Quick Tunnel 安装/运行状态（供 Dashboard 使用）
/api/tunnels/cloudflared	POST	启用/禁用 Cloudflare Quick Tunnel（action=enable/disable）

CLI Tools CLI 工具状态

端点	Method	说明
/api/cli-tools/claude-settings	GET	Claude CLI 状态
/api/cli-tools/codex-settings	GET	Codex CLI 状态
/api/cli-tools/droid-settings	GET	Droid CLI 状态
/api/cli-tools/openclaw-settings	GET	OpenClaw CLI 状态
/api/cli-tools/runtime/[toolId]	GET	通用 CLI 运行时

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

ACP Agents ACP 代理

端点	Method	说明
/api/acp/agents	GET	列出所有检测到的代理（内置 + 自定义）及状态
/api/acp/agents	POST	添加自定义代理或刷新检测缓存
/api/acp/agents	DELETE	按id查询参数移除自定义代理

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

Resilience & Rate Limits 弹性与速率限制

端点	Method	说明
/api/resilience	GET/PATCH	读取/更新请求队列、连接冷却、Provider 熔断与等待设置
/api/resilience/reset	POST	重置 Provider 熔断器
/api/rate-limits	GET	每账号速率限制状态
/api/rate-limit	GET	全局速率限制配置

Evals 评估

端点	Method	说明
/api/evals	GET/POST	列出评估套件 / 运行评估

Policies 策略

端点	Method	说明
/api/policies	GET/POST/DELETE	管理路由策略

Compliance 合规

端点	Method	说明
/api/compliance/audit-log	GET	合规审计日志（最近 N 条）

v1beta（Gemini 兼容）

端点	Method	说明
/v1beta/models	GET	以 Gemini 格式列出模型
/v1beta/models/{...path}	POST	GeminigenerateContent端点

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

Internal / System APIs 内部与系统 API

端点	Method	说明
/api/init	GET	应用初始化检查（首次运行使用）
/api/tags	GET	Ollama 兼容的模型标签（供 Ollama 客户端）
/api/restart	POST	触发优雅重启
/api/shutdown	POST	触发优雅关机
/api/system/env/repair	POST	修复 OAuth Provider 环境变量
/api/system-info	GET	生成系统诊断报告

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

OAuth Environment Repair 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 }

支持的模型：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/*请求按以下流水线处理：

1. 客户端向/v1/*发送请求；
2. 路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration；
3. 解析模型（直接 provider/model，或别名 / Combo）；
4. 从本地数据库选择凭据，并按账号可用性过滤；
5. 对话请求进入handleChatCore—— 格式检测、翻译、缓存检查、幂等检查；
6. Provider executor 向上游发送请求；
7. 响应翻译回客户端格式（对话），嵌入/图像/音频则原样返回；
8. 记录用量与日志；
9. 出错时按 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_KEY=true时可选要求 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.md
• Provider 与模型参考：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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute