企业官网建设流程全解析

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, 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 家以上提供商（其中 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 Compatibility（Ollama 兼容）
• 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_type（RFC 7231 语义，与 OpenAI/Anthropic 边界行为对齐）；
• 通过admitChatRequest+admitChatStructure做入口接纳（admission）控制：在 JSON 解析前按真实字节数预占重型容量，避免缺失或虚报的Content-Length绕过限制；
• 请求体只json()解析一次，随后交给handleChat（实现在 src/sse/handlers/chat.ts）做深层校验（messages/model/temperature/top_p/max_tokens/n 等），路由层仅保留一个刻意宽松的 shape schema（.passthrough()），避免在热路径上重复拒绝合法请求。

自定义响应头

请求与响应均可携带X-OmniRoute-*系列头，用于缓存控制、会话亲和与幂等去重：

Nginx 提示：若依赖下划线请求头（例如x_session_id），需在 Nginx 中开启underscores_in_headers on;。

英文原版（docs/reference/API_REFERENCE.md）进一步补充了响应侧遥测头，法语版同样适用：

• 路由决策：X-OmniRoute-Decision返回strategy=<名称>; provider=<别名>; latency_ms=<n>（<名称>为组合路由策略名，非组合请求则为single），每次完成响应都会携带；
• 成本遥测：非流式成功响应会附带X-OmniRoute-Response-Cost（USD，固定 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 策略，最终交予handleEmbedding（open-sse/handlers/embeddings.ts）执行。英文原版还说明：注册表声明支持多模态的模型可接受最多 32 个提供商中立的媒体条目（text/image/audio/video/document），内联 base64 媒体单条目上限 8 MiB、跨请求合计 16 MiB；Jina 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" }

可用提供商：OpenAI（GPT Image 2）、xAI（Grok Image）、Together AI（FLUX）、Fireworks AI、Nebius（FLUX）、Hyperbolic、NanoBanana、OpenRouter、SD WebUI（本地）、ComfyUI（本地）。本地推理部署（SD WebUI/ComfyUI）可通过 OmniRoute 纳入统一的路由与自动故障转移体系。

# 列出所有图像模型 GET /v1/images/generations

List 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）模型。

英文原版进一步说明了两个对客户端影响显著的细节：

1. 模型前缀模式（?prefix=）：目录中大部分模型以提供商前缀发布，可通过MODELS_CATALOG_PREFIX_MODE特性开关控制，并支持按请求覆盖——prefix=alias（每模型一个短别名）、prefix=dual（服务器默认，同时输出cc/…与claude/…两种 ID，目录规模约翻倍）、prefix=canonical（仅完整提供商前缀）。
2. 无思考变体（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 等生态的兼容入口，客户端可以“原格式进、原格式出”：

专用提供商路由（Dedicated Provider Routes）

POST /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）

提供商管理（Provider Management）

OAuth 流程

路由与配置（Routing & Config）

用量与分析（Usage & Analytics）

设置（Settings）

监控（Monitoring）

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

云同步（Cloud Sync）

隧洞（Tunnels）

CLI 工具

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

ACP Agent（Agent Client Protocol）

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

弹性与速率限制（Resilience & Rate Limits）

评测（Evals）

策略（Policies）

合规（Compliance）

v1beta（Gemini 兼容）

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

内部 / 系统 API（Internal / System APIs）

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

OAuth 环境修复（v3.6.1+）

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

响应示例：

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

受支持模型 ID：deepgram/nova-3、assemblyai/best（英文原版补充：openai/whisper-1需 OpenAI Key；openrouter/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 Compatibility（Ollama 兼容）

面向使用 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 说明（英文原版，setBudgetSchema）：apiKeyId必填；dailyLimitUsd、weeklyLimitUsd、monthlyLimitUsd三者至少其一大于 0；可选字段warningThreshold（0–1）、resetInterval（daily/weekly/monthly）、resetTime（HH:MM）。旧的{keyId, limit, period}形状返回400 Bad Request。

Request Processing（请求处理链路）

法语版文档给出了一个清晰的九步处理流程：

1. 客户端向/v1/*发送请求
2. 路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration
3. 解析模型（直连 provider/model，或别名/组合）
4. 从本地数据库选择凭据，并过滤账号可用性
5. 聊天请求进入handleChatCore：格式检测、翻译、缓存检查、幂等检查
6. 提供商执行器向远端发送请求
7. 响应翻译回客户端格式（聊天），或原样返回（嵌入/图像/音频）
8. 记录用量与日志
9. 出错时按组合（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_PASSWORD；
• requireLogin可通过/api/settings/require-login切换；
• /v1/*路由在REQUIRE_API_KEY=true时可选要求 Bearer API Key。

这里区分两个认证面：/v1/*推理面使用普通 API Key（Bearer）；/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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute