企业官网建设流程全解析

OmniRoute API 参考：OpenAI 兼容网关的完整端点指南与请求处理流程

【免费下载链接】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 统一 AI 网关的 API 完整参考指南，覆盖公共/v1推理接口（Chat Completions、Embeddings、图像生成、音频转写、OCR 等）、多协议兼容端点（Anthropic / Gemini / Ollama）、管理面 Dashboard API（Provider 管理、用量分析、缓存、备份、Webhooks）以及认证与请求处理全链路。读完本文，你将掌握 OmniRoute 每个端点的方法、请求/响应格式与鉴权方式，并理解请求从进入网关到返回结果的完整处理流水线，可直接用于接入 Claude Code、Codex、Cursor 等客户端或自建调用。

本文以 docs/i18n/ko/docs/reference/API_REFERENCE.md（韩语版，与英文主文档 docs/reference/API_REFERENCE.md 内容一致）为骨架，并结合仓库源码与路由实现进行扩展。机器可读的完整接口定义见 docs/openapi.yaml，src/app/api/下的路由树是端点实现的权威来源。

目录

• Chat Completions
• Embeddings
• Image Generation
• List Models
• Compatibility Endpoints
• Semantic Cache
• Dashboard & Management
• Request Processing
• Authentication

Chat Completions

对话补全走 OpenAI 格式，是网关的核心入口：

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 }

模型 ID 采用provider/model前缀结构（如cc/claude-opus-4-6），也支持别名（alias）与组合（combo）路由。请求体由 Zod schema 校验，失败时返回 4xx。

自定义请求/响应头

Nginx 提示：如果依赖下划线头（例如x_session_id），需要在 Nginx 中启用underscores_in_headers on;。

这些响应头在源码中集中定义于 src/shared/constants/headers.ts 的OMNIROUTE_RESPONSE_HEADERS常量，其中包含cache、cacheHit、cacheLatency、costSaved、decision、latencyMs、model、provider、requestId、responseCost、tokensIn、tokensOut、version等完整字段，可据此在客户端解析成本与路由信息。

成本遥测响应头

非流式成功响应还会携带一组X-OmniRoute-*成本遥测头：X-OmniRoute-Response-Cost（USD，固定 10 位小数，免费/未定价时为0.0000000000）、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。这些头由 Chat Completions、/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）共同发出。

缓存命中成本语义：语义缓存命中（X-OmniRoute-Cache-Hit: true）时不发起上游调用，因此X-OmniRoute-Response-Cost为0.0000000000（命中服务的增量成本）；原本应产生的成本单独通过X-OmniRoute-Cost-Saved上报。计费消费方应累加X-OmniRoute-Response-Cost（命中不计费），缓存分析则可聚合X-OmniRoute-Cost-Saved。

压缩计划覆盖头x-omniroute-compression

该请求头可按请求覆盖压缩计划，优先级最高——高于路由组合覆盖、激活配置文件、自动触发与面板默认值。取值：

注意：未知值会被忽略（请求不会被拒绝），解析会回退到常规优先级；多个组合同名时请传组合id以获得确定性匹配；名为off或default的组合不能按名称选择（这两个关键字优先解释），需用其 id 引用；全局压缩总开关是硬性门槛，全局禁用时该头无法启用压缩。实际应用的压缩方案会在响应头中回显：X-OmniRoute-Compression: <mode>; source=<source>，其中<source>为request-header、routing-override、active-profile、auto-trigger、default或off之一。

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。列出全部嵌入模型：

GET /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（本地）。列出全部图像模型：

GET /v1/images/generations

List Models

GET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回全部聊天、嵌入、图像模型 + 组合

模型 ID 前缀（?prefix=）

模型 ID 的前缀形式由MODELS_CATALOG_PREFIX_MODE特性开关控制，也可按请求用查询参数覆盖：

GET /v1/models?prefix=alias # 每个模型一个 ID —— 短别名前缀 GET /v1/models?prefix=dual # 两种形式（服务器默认） GET /v1/models?prefix=canonical # 仅完整 provider-id 前缀

dual模式的镜像条目还带有parent字段指向主 ID。渲染模型选择器的客户端应请求?prefix=alias（例如 OmniCopilot VS Code 扩展即如此）。

无思考（no-thinking）模型变体

对于支持思考的 Claude 模型，/v1/models还会公布一个no-thinking变体，ID 前缀为claude-3-omniroute-no-thinking/：

claude-3-omniroute-no-thinking/<provider>/<model>

选择该 ID（例如在始终附加thinking块的 Claude Code 配置中）会解析回真实<provider>/<model>并抑制推理：在/v1/messages路径上为thinking:{type:"disabled"}，在/v1/chat/completions路径上丢弃reasoning/reasoning_effort字段。该变体仅对支持思考且接受disabled的 Claude 模型列出；操作员可通过ModelSpec.noThinkingAlias按模型强制开启或关闭该变体。对应实现位于 open-sse/utils/noThinkingAlias.ts。

Compatibility Endpoints

专用提供商路由

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

提供商前缀缺失时会自动补全。模型与提供商不匹配时返回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 } }

命中时延影响

语义缓存命中时响应不经上游调用直接返回，因此X-OmniRoute-Response-Latency接近为零（与原始上游时延无关）。对时延敏感的客户端（基准测试、p50/p99 监控）应检查X-OmniRoute-Cache-Latency响应头：

按 Key 绕过缓存

API Key 可通过cacheDefaultMode选择退出语义缓存读取：

在创建 Key（POST /api/keys）或更新（PATCH /api/keys/[id]）时设置：

{ "cacheDefaultMode": "bypass" }

按请求绕过缓存

任何请求无论 Key 设置如何都可绕过缓存：

X-OmniRoute-No-Cache: true

Dashboard & Management

管理路由（/api/*，公共 auth/login 除外）不由普通推理 API Key 授权。凭证族、作用域与 curl 示例见 Management Authentication。

Authentication

Provider Management

OAuth Flows

Routing & Config

Usage & Analytics

Settings

Monitoring

Backup & Export/Import

Cloud Sync

Tunnels

CLI Tools

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

ACP Agents

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 兼容性的客户端。

Internal / System APIs

注意：这些端点由系统内部使用或用于 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 }

支持提供商：deepgram/nova-3、assemblyai/best。

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

Ollama Compatibility

面向使用 Ollama API 格式的客户端：

# Chat 端点（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 } } }

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

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

Chat 核心链路在 src/sse/handlers/chat.ts 中实现，包含路由模型解析、凭证配额预检、组合路由（handleComboChat）与压缩设置解析等关键环节。完整架构参考：ARCHITECTURE.md。

Authentication

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

v3.8.0 破坏性变更：/api/v1/agents/tasks/*与冷却管理端点现在要求管理认证（Dashboardauth_tokencookie 或管理作用域 API Key）。此前未认证调用这些路由的客户端将收到401 Unauthorized。

延伸阅读

• API 参考（英文主文档）：包含独占托管会话租约、文件/批处理 API、WebSocket 流式、搜索/网页抓取、A2A/MCP 服务器等扩展端点
• docs/openapi.yaml：机器可读的完整 OpenAPI 定义
• Management Authentication：管理面四类凭证族详解
• ARCHITECTURE.md：整体架构与请求流水线
• THINKING_BUDGET.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