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

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, RTKCaveman 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 APIProvider 管理、用量分析、缓存、备份、Webhooks以及认证与请求处理全链路。读完本文你将掌握 OmniRoute 每个端点的方法、请求/响应格式与鉴权方式并理解请求从进入网关到返回结果的完整处理流水线可直接用于接入 Claude Code、Codex、Cursor 等客户端或自建调用。本文以 docs/i18n/ko/docs/reference/API_REFERENCE.md韩语版与英文主文档 docs/reference/API_REFERENCE.md 内容一致为骨架并结合仓库源码与路由实现进行扩展。机器可读的完整接口定义见 docs/openapi.yamlsrc/app/api/下的路由树是端点实现的权威来源。目录Chat CompletionsEmbeddingsImage GenerationList ModelsCompatibility EndpointsSemantic CacheDashboard ManagementRequest ProcessingAuthenticationChat 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。自定义请求/响应头Header方向说明X-OmniRoute-No-Cache请求设为true时绕过语义缓存X-OmniRoute-Progress请求设为true时启用进度事件X-Session-Id请求外部会话亲和性的粘性会话键x_session_id请求下划线变体直连 HTTP 时同样接受Idempotency-Key请求去重键5 秒窗口X-Request-Id请求备选去重键X-OmniRoute-Cache响应HIT或MISS仅非流式X-OmniRoute-Idempotent响应为true表示已去重X-OmniRoute-Progress响应为enabled表示进度追踪已开启X-OmniRoute-Session-Id响应OmniRoute 实际使用的会话 IDNginx 提示如果依赖下划线头例如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-CostUSD固定 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该请求头可按请求覆盖压缩计划优先级最高——高于路由组合覆盖、激活配置文件、自动触发与面板默认值。取值值效果off本请求不压缩default使用面板派生的 Default 配置忽略激活的配置文件engine:id使用单个引擎如engine:rtkcombo具名组合先按名称不区分大小写匹配再按 id 匹配注意未知值会被忽略请求不会被拒绝解析会回退到常规优先级多个组合同名时请传组合id以获得确定性匹配名为off或default的组合不能按名称选择这两个关键字优先解释需用其 id 引用全局压缩总开关是硬性门槛全局禁用时该头无法启用压缩。实际应用的压缩方案会在响应头中回显X-OmniRoute-Compression: mode; sourcesource其中source为request-header、routing-override、active-profile、auto-trigger、default或off之一。EmbeddingsPOST /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/embeddingsImage GenerationPOST /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 }可用提供商OpenAIGPT Image 2、xAIGrok Image、Together AIFLUX、Fireworks AI、NebiusFLUX、Hyperbolic、NanoBanana、OpenRouter、SD WebUI本地、ComfyUI本地。列出全部图像模型GET /v1/images/generationsList ModelsGET /v1/models Authorization: Bearer your-api-key → 以 OpenAI 格式返回全部聊天、嵌入、图像模型 组合模型 ID 前缀?prefix模型 ID 的前缀形式由MODELS_CATALOG_PREFIX_MODE特性开关控制也可按请求用查询参数覆盖GET /v1/models?prefixalias # 每个模型一个 ID —— 短别名前缀 GET /v1/models?prefixdual # 两种形式服务器默认 GET /v1/models?prefixcanonical # 仅完整 provider-id 前缀模式输出说明dualcc/claude-sonnet-4-6与claude/claude-sonnet-4-6默认。两个 ID 路由到同一模型保证硬编码任一形式的客户端配置继续工作目录规模约翻倍aliascc/claude-sonnet-4-6每模型一条。无独立别名的提供商仍输出其条目不丢失canonicalclaude/claude-sonnet-4-6每模型一条使用完整 provider-id 前缀dual模式的镜像条目还带有parent字段指向主 ID。渲染模型选择器的客户端应请求?prefixalias例如 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/chat/completionsOpenAIPOST/v1/messagesAnthropicPOST/v1/responsesOpenAI ResponsesPOST/v1/embeddingsOpenAIPOST/v1/images/generationsOpenAIGET/v1/modelsOpenAIPOST/v1/messages/count_tokensAnthropicGET/v1beta/modelsGeminiPOST/v1beta/models/{...path}Gemini generateContentPOST/v1/api/chatOllama专用提供商路由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响应头值含义synthetic响应来自缓存时延非真实上游时间缺失来自真实上游调用按 Key 绕过缓存API Key 可通过cacheDefaultMode选择退出语义缓存读取值行为legacy正常缓存行为默认bypass完全跳过缓存查找始终命中上游在创建 KeyPOST /api/keys或更新PATCH /api/keys/[id]时设置{ cacheDefaultMode: bypass }按请求绕过缓存任何请求无论 Key 设置如何都可绕过缓存X-OmniRoute-No-Cache: trueDashboard Management管理路由/api/*公共 auth/login 除外不由普通推理 API Key 授权。凭证族、作用域与 curl 示例见 Management Authentication。Authentication端点方法说明/api/auth/loginPOST登录/api/auth/logoutPOST登出/api/settings/require-loginGET/PUT切换是否要求登录Provider Management端点方法说明/api/providersGET/POST列出 / 创建 Provider/api/providers/[id]GET/PUT/DELETE管理单个 Provider/api/providers/[id]/testPOST测试 Provider 连接/api/providers/[id]/modelsGET列出 Provider 模型/api/providers/validatePOST校验 Provider 配置/api/provider-nodes*多种Provider 节点管理/api/provider-modelsGET/POST/PATCH/DELETE自定义模型添加、更新、隐藏/显示、删除OAuth Flows端点方法说明/api/oauth/[provider]/[action]多种Provider 专属 OAuthRouting Config端点方法说明/api/models/aliasGET/POST模型别名/api/models/catalogGET按 Provider 类型列出全部模型/api/combos*多种组合管理/api/keys*多种API Key 管理/api/pricingGET模型定价Usage Analytics端点方法说明/api/usage/historyGET用量历史/api/usage/logsGET用量日志/api/usage/request-logsGET请求级日志/api/usage/[connectionId]GET单连接用量Settings端点方法说明/api/settingsGET/PUT/PATCH通用设置/api/settings/proxyGET/PUT网络代理配置/api/settings/proxy/testPOST测试代理连接/api/settings/ip-filterGET/PUTIP 白名单/黑名单/api/settings/thinking-budgetGET/PUT推理 token 预算/api/settings/system-promptGET/PUT全局系统提示词Monitoring端点方法说明/api/sessionsGET活跃会话追踪/api/rate-limitsGET每账户限流/api/monitoring/healthGET健康检查 Provider 摘要catalogCount、configuredCount、activeCount、monitoredCount/api/cache/statsGET/DELETE缓存统计 / 清空Backup Export/Import端点方法说明/api/db-backupsGET列出可用备份/api/db-backupsPUT创建手动备份/api/db-backupsPOST从指定备份恢复/api/db-backups/exportGET以 .sqlite 文件下载数据库/api/db-backups/importPOST上传 .sqlite 文件替换数据库/api/db-backups/exportAllGET以 .tar.gz 归档下载完整备份Cloud Sync端点方法说明/api/sync/cloud多种云同步操作/api/sync/initializePOST初始化同步/api/cloud/*多种云管理Tunnels端点方法说明/api/tunnels/cloudflaredGET读取 Cloudflare Quick Tunnel 安装/运行状态供 Dashboard 展示/api/tunnels/cloudflaredPOST启用或禁用 Cloudflare Quick Tunnelactionenable/disableCLI Tools端点方法说明/api/cli-tools/claude-settingsGETClaude CLI 状态/api/cli-tools/codex-settingsGETCodex CLI 状态/api/cli-tools/droid-settingsGETDroid CLI 状态/api/cli-tools/openclaw-settingsGETOpenClaw CLI 状态/api/cli-tools/runtime/[toolId]GET通用 CLI 运行时CLI 响应包含installed、runnable、command、commandPath、runtimeMode、reason。ACP Agents端点方法说明/api/acp/agentsGET列出所有检测到的 Agent内置 自定义及状态/api/acp/agentsPOST添加自定义 Agent 或刷新检测缓存/api/acp/agentsDELETE按id查询参数移除自定义 AgentGET 响应包含agents[]id、name、binary、version、installed、protocol、isCustom与summarytotal、installed、notFound、builtIn、custom。Resilience Rate Limits端点方法说明/api/resilienceGET/PATCH读取/更新请求队列、连接冷却、Provider 熔断与等待设置/api/resilience/resetPOST重置 Provider 熔断器/api/rate-limitsGET每账户限流状态/api/rate-limitGET全局限流配置Evals端点方法说明/api/evalsGET/POST列出评测套件 / 运行评测Policies端点方法说明/api/policiesGET/POST/DELETE管理路由策略Compliance端点方法说明/api/compliance/audit-logGET合规审计日志最近 N 条v1betaGemini 兼容端点方法说明/v1beta/modelsGET以 Gemini 格式列出模型/v1beta/models/{...path}POSTGeminigenerateContent端点这些端点镜像 Gemini API 格式面向期望原生 Gemini SDK 兼容性的客户端。Internal / System APIs端点方法说明/api/initGET应用初始化检查首次运行时使用/api/tagsGETOllama 兼容模型标签供 Ollama 客户端/api/restartPOST触发优雅服务重启/api/shutdownPOST触发优雅服务关闭/api/system/env/repairPOST修复 OAuth Provider 环境变量/api/system-infoGET生成系统诊断报告注意这些端点由系统内部使用或用于 Ollama 客户端兼容通常不由最终用户调用。OAuth 环境变量修复v3.6.1POST /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 TranscriptionPOST /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 filerecording.mp3 \ -F modeldeepgram/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客户端发送请求到/v1/*路由处理器调用handleChat、handleEmbedding、handleAudioTranscription或handleImageGeneration解析模型直接 provider/model或别名/组合从本地数据库选择凭证并经过账户可用性过滤Chat 流程进入handleChatCore—— 格式检测、翻译、缓存检查、幂等检查Provider 执行器向上游发送请求响应翻译回客户端格式chat或原样返回embeddings/images/audio记录用量/日志出错时按组合规则应用回退Chat 核心链路在 src/sse/handlers/chat.ts 中实现包含路由模型解析、凭证配额预检、组合路由handleComboChat与压缩设置解析等关键环节。完整架构参考ARCHITECTURE.md。AuthenticationDashboard 路由/dashboard/*使用auth_tokencookie登录使用已保存的密码哈希回退到INITIAL_PASSWORDrequireLogin可通过/api/settings/require-login切换当REQUIRE_API_KEYtrue时/v1/*路由可选要求 Bearer API Keyv3.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, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考