Call Multiple LLMs, One API: GPT, Claude, and Gemini 用一个 API 安全调用多个 LLM
One client contract can reach several model families through aliases and provider adapters. The integration becomes simpler only when capability differences, native evidence and migration tests remain explicit.
一个客户端契约可通过别名与供应商适配器访问多个模型家族。只有能力差异、原生证据与迁移测试仍然显式时，集成才真正更简单。
TL;DR
Applications share authentication, request envelopes, tracing and operational controls.
GPT, Claude and Gemini differ by model, endpoint, version, tools, context, modalities and policy.
Resolve a workload alias only to endpoints that satisfy required behavior.
Return provider and model identity, request IDs, usage, route and transformations with normalized output.
应用共享认证、请求封装、Tracing 与运营控制。
GPT、Claude 与 Gemini 因模型、端点、版本、工具、上下文、模态与策略而异。
工作负载别名只能解析到满足必需行为的端点。
随标准化输出返回供应商与模型身份、请求 ID、用量、路由与转换。
What the unified call should standardize 统一调用应标准化什么
Standardize application concerns that are genuinely common: service identity, tenant, trace context, workload alias, messages, timeout, budget, required capabilities and a stable response envelope. Resolve the alias from a versioned catalog before provider translation.
标准化真正通用的应用关注点：服务身份、租户、调用链上下文、工作负载别名、Message、超时、预算、所需能力与稳定响应封装。在供应商转换前，从版本化目录解析别名。
Do not force every feature into the common denominator. Use typed extensions for provider-specific tools, reasoning, schema, media or caching controls. Reject missing required capabilities before the call rather than silently degrading them.
不要把所有功能都压进最低共同分母。供应商特定工具、推理、结构定义、媒体或缓存控制应使用类型化扩展；在调用前拒绝缺失必需能力，而不是静默降级。
One-API integration layers 单一 API 集成层
| Layer 层 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Canonical request 规范请求 | One SDK sends identity, messages, workload alias and required capabilities. 一个 SDK 发送身份、Message、工作负载别名与所需能力。 | Keep timeout, budget, trace and tenant explicit; avoid provider assumptions in app code. 显式保留超时、预算、调用链与租户，避免应用代码假设供应商。 |
| Capability catalog 能力目录 | Model aliases map to eligible versions and endpoints. 模型别名映射到合格版本与端点。 | Source and refresh tools, schemas, context, modalities, region, policy and lifecycle. 为工具、结构定义、上下文、模态、区域、策略与生命周期标注来源并刷新。 |
| Router 路由器 | Filters and chooses among eligible GPT, Claude or Gemini endpoints. 在合格 GPT、Claude 或 Gemini 端点中过滤并选择。 | Record candidate set, exclusions, policy, route and fallback conditions. 记录候选集、排除项、策略、路由与故障切换条件。 |
| Provider adapters 供应商适配器 | Translate canonical fields to supported native semantics. 把规范字段转换为受支持的原生语义。 | Contract-test tools, streams, structured output, errors and usage for each adapter. 为每个适配器契约测试工具、流、结构化输出、错误与用量。 |
| Response envelope 响应封装 | Applications receive stable fields plus native evidence. 应用接收稳定字段与原生证据。 | Preserve provider, model, request ID, route, attempts, usage units and transformations. 保留供应商、模型、请求 ID、路由、尝试、用量单位与转换。 |
Build the common contract around workloads 围绕工作负载构建通用契约
Name the task contract, not a vendor model, when portability is required.
Declare tools, schema, modalities, context, streaming, region and policy as hard flags.
Allow opt-in native features without pretending every provider supports them.
Keep canonical and native identity together for debugging, cost and audit.
需要可移植性时，命名任务契约而不是供应商模型。
把工具、结构定义、模态、上下文、流、区域与策略声明为硬性 Flag。
允许选择原生功能，同时不假装每个供应商都支持。
把规范与原生身份并存，用于调试、成本与审计。
Prove each model path 验证每条模型路径
- Create golden requests for each production workload and required capability combination.
- Run contract tests against every eligible GPT, Claude and Gemini endpoint.
- Diff outputs, tools, streams, errors, usage and latency under real payloads.
- Canary route changes and block on workload-specific invariant regressions.
- Keep provider-native direct paths for diagnosis and tested rollback.
- 为每个生产负载与必需能力组合建立 Golden 请求。
- 对每个合格 GPT、Claude 与 Gemini 端点运行契约测试。
- 在真实请求数据下对比输出、工具、流、错误、用量与延迟。
- 灰度路由变更，并在工作负载特定不变量回归时阻断。
- 保留供应商原生直连路径，用于诊断与已测试回滚。
Use aliases above typed provider adapters 在类型化供应商适配器之上使用别名
The application sends a canonical request with workload alias and required capabilities. A catalog expands eligible endpoints; a policy router selects one; a typed adapter maps the request. The normalized response returns with provider-native identity and evidence. Unsupported requirements fail before execution, and fallback uses only verified equivalents.
应用发送带工作负载别名与所需能力的规范请求；目录展开合格端点，策略路由器选择一个，类型化适配器映射请求。标准化响应携带供应商原生身份与证据返回。不支持的要求在执行前失败，故障切换也只使用已验证等价项。
Production rule: one client contract must not become one vague promise that every model behaves the same.
生产规则：一个客户端契约不能变成“所有模型行为相同”的模糊承诺。
One model API plus one capability interface 一个模型 API 加一个能力接口
The unified model API gives an agent consistent inference access. QVeris gives that agent Discover → Inspect → Call access to external APIs, tools, services and live data. Stack them as model interface plus capability interface, sharing workload identity and trace context.
统一模型 API 为智能体提供一致推理访问；QVeris 以 Discover → Inspect → 调用提供外部 API、工具、服务与实时数据访问。把两者叠加为模型接口与能力接口，并共享工作负载身份与调用链上下文。
Keep one request shape and explicit model aliases 保持一个请求 Shape 与显式模型别名
A unified endpoint is useful only when callers can predict what each alias means. Use product-owned aliases, return the native provider and exact model in the response metadata, and reject unknown aliases instead of silently choosing a default.
统一端点只有在调用方能预测每个别名含义时才有价值。使用产品自有别名，在响应 Metadata 中返回原生供应商与准确模型，并拒绝未知别名，而不是静默选择默认值。
for alias in support-fast support-quality; do
curl --fail-with-body "$LLM_GATEWAY_BASE_URL/chat/completions" -H "Authorization: Bearer $LLM_GATEWAY_API_KEY" -H "Content-Type: application/json" -H "X-Workload: support-answer" -d "{"model":"$alias","messages":[{"role":"user","content":"Reply $alias OK"}]}"
done
- Document each alias's capability, quality gate, region, lifecycle, and owner.
- Require response metadata to expose chosen provider, native model, policy version, and usage.
- Run the same golden workload against every alias before changing its mapping.
- 记录每个别名的能力、质量门槛、区域、生命周期与 Owner。
- 要求响应 Metadata 暴露最终供应商、原生模型、Policy Version 与用量。
- 修改别名 Mapping 前，用同一 Golden 工作负载测试所有候选。
Verified implementation reference: OpenAI Chat Completions reference.
实施参考已根据官方资料核验：OpenAI Chat Completions reference。
Define the Production Contract for calling multiple LLMs through one API定义通过一个 API 调用多个 LLM的生产契约
For One API for GPT, Claude, and Gemini, protocol similarity lowers integration effort, but it does not guarantee behavioral parity. Put a versioned application contract between product code and the provider path so change remains testable and reversible.
针对“一个 API 调用三类模型”，协议相似可以降低集成工作量，却不能保证行为等价。应在产品代码与供应商路径之间建立版本化应用契约，让变更保持可测试、可回滚。
Document canonical messages, model aliases, provider-specific options, streaming events, structured output, tools, usage normalization, and error mapping. Mark each item as required, optional, provider-native, or unsupported, and assign an owner for any transformation that changes its meaning.
记录规范消息、模型别名、供应商专属选项、流式事件、结构化输出、工具、用量规范化和错误映射。把每一项标记为必需、可选、供应商原生或不支持，并为任何改变语义的转换明确负责人。
To validate One API for GPT, Claude, and Gemini, create fixtures for short and long prompts, Unicode, streaming, JSON schema, parallel tools, refusals, cancellation, malformed input, and rate limits. Check required fields and event order instead of accepting one plausible text answer.
验证“一个 API 调用三类模型”时，为短与长提示词、Unicode、流式、JSON Schema、并行工具、拒绝、取消、畸形输入和限流建立 Fixture，检查必需字段与事件顺序，而不是接受一个看似合理的文本答案。
When operating One API for GPT, Claude, and Gemini, trace internal request ID, resolved model and provider, model version, transformations, retries, latency, token classes, cost source, policy result, and output validation. Redact secrets without deleting the context needed to reproduce failure.
运营“一个 API 调用三类模型”时，追踪内部请求 ID、解析后的模型与供应商、模型版本、转换、重试、延迟、Token 类别、成本来源、策略结果和输出校验，在脱敏密钥的同时保留复现失败所需上下文。
Before rolling out One API for GPT, Claude, and Gemini, shadow representative traffic, classify semantic differences, canary by reversible workload, monitor task completion and tail behavior, and keep the previous route available until rollback and return-to-primary have been rehearsed.
上线“一个 API 调用三类模型”前，运行代表性影子流量，分类语义差异，按可逆工作负载进行金丝雀发布，监控任务完成与长尾行为，并在演练回滚和恢复主路径之前保留原有路由。
FAQ
A common core often can, but advanced features and exact semantics still vary by endpoint.
Yes in evidence, even when applications use workload aliases for routing.
Only when the alternate passes the workload's capability and quality contract.
通用核心通常可以，但高级功能与精确语义仍因端点而异。
应在证据中暴露，即使应用使用工作负载别名进行路由。
只有备用项通过工作负载能力与质量契约时才可以。