模型服务提供商路由

将请求路由到最佳模型服务提供商

OpenRouter 会将请求路由到你所用模型当前最佳的可用模型服务提供商。默认情况下，请求会在领先的服务提供商之间进行负载均衡，以最大化可用性。

你可以在 聊天补全（Chat Completions） 请求体的 provider 对象中自定义路由方式。

provider 对象可以包含以下字段：

基于价格的负载均衡（默认策略）

对于请求中的每个模型，OpenRouter 的默认行为是在各服务提供商之间负载均衡请求，并优先考虑价格。

如果你对吞吐量比对价格更敏感，可以使用 sort 字段显式优先考虑吞吐量。

以下是 OpenRouter 的默认负载均衡策略：

1. 优先选择过去 30 秒内未出现明显故障的服务提供商。
2. 在稳定的服务提供商中，查看成本最低的候选者，并按价格平方的倒数加权选择其一（见下方示例）。
3. 将其余服务提供商作为回退。

如果在服务提供商偏好中设置了 sort 或 order，负载均衡将被禁用。

服务提供商排序

如上所述，OpenRouter 会基于价格进行负载均衡，同时考虑可用性。

如果你希望显式优先考虑某一服务提供商属性，可以在 provider 偏好中加入 sort 字段。此时负载均衡将被禁用，路由器会按顺序尝试各服务提供商。

三种排序选项为：

• "price"：优先选择最低价格
• "throughput"：优先选择最高吞吐量
• "latency"：优先选择最低延迟

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.3-70b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: 'throughput',
  },
  stream: false,
});

若要始终优先考虑低价格且不应用任何负载均衡，请将 sort 设为 "price"。

若要始终优先考虑低延迟且不应用任何负载均衡，请将 sort 设为 "latency"。

Nitro 快捷方式

你可以在任意模型 slug 后追加 :nitro，作为按吞吐量排序的快捷方式。这与将 provider.sort 设为 "throughput" 完全等效。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.3-70b-instruct:nitro',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: false,
});

最低价快捷方式

你可以在任意模型 slug 后追加 :floor，作为按价格排序的快捷方式。这与将 provider.sort 设为 "price" 完全等效。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.3-70b-instruct:floor',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: false,
});

使用分区进行高级排序

在使用模型回退时，可以将 sort 指定为对象，并附带额外选项，以控制端点在多个模型之间如何排序。

默认情况下，当你指定多个模型（回退）时，OpenRouter 会先按模型对端点分组，然后再排序。这意味着无论性能特征如何，都会始终先尝试主模型的端点。将 partition 设为 "none" 会取消这种分组，从而允许跨所有模型对端点进行全局排序。

若要显式使用默认行为，请设置 partition: "model"。关于模型回退的工作方式，详见模型回退。

用例 1：路由到吞吐量最高或延迟最低的模型

当你有多个可接受的模型，并希望使用当前性能最好的那一个时，请将 partition: "none" 与按吞吐量或延迟排序结合使用。这在你更关心速度而非特定模型时很有用。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5-mini',
    'google/gemini-3-flash-preview',
  ],
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: {
      by: 'throughput',
      partition: 'none',
    },
  },
  stream: false,
});

在此示例中，OpenRouter 会路由到这三个模型中当前吞吐量最高的端点，而不是始终先尝试 Claude。

性能阈值

你可以设置最低吞吐量或最高延迟阈值来筛选端点。未达到这些阈值的端点会被降低优先级（移到列表末尾），而不是被完全排除。

百分位的工作方式

OpenRouter 使用滚动 5 分钟窗口计算的百分位统计，跟踪每个模型和每个服务提供商的延迟与吞吐量指标。可用的百分位包括：

• p50（中位数）：50% 的请求表现优于该值
• p75：75% 的请求表现优于该值
• p90：90% 的请求表现优于该值
• p99：99% 的请求表现优于该值

较高的百分位（如 p90 或 p99）能让你对最差情况的性能更有把握，而较低的百分位（如 p50）反映的是典型性能。例如，如果某个模型与服务提供商的 p90 延迟为 2 秒，意味着 90% 的请求会在 2 秒内完成。

当你指定多个百分位截止值时，模型和该服务提供商必须同时满足所有指定的截止值，才会进入优先组。这样你就可以同时设置典型性能和最差情况性能要求。

何时使用百分位偏好

基于百分位的路由适合你需要可预期性能特征的场景：

• 实时应用：使用 p90 或 p99 延迟阈值，确保面向用户的功能具有稳定的响应时间
• 批处理：当你更关心平均性能而非最差情况时，使用 p50 吞吐量阈值
• 服务级别协议（SLA）合规：使用多个百分位截止值，确保服务提供商在不同性能层级都满足你的服务级别协议
• 成本优化：与 sort: "price" 结合，选择仍能满足性能要求的最便宜服务提供商

用例 2：找到满足性能要求的最便宜模型

将 partition: "none" 与性能阈值结合，可以在多个模型中找到满足性能要求的最便宜选项。这在你有性能下限但希望尽量降低成本时很有用。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5-mini',
    'google/gemini-3-flash-preview',
  ],
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: {
      by: 'price',
      partition: 'none',
    },
    preferredMinThroughput: {
      p90: 50, // 优先选择过去 5 分钟内 90% 的请求吞吐量 >50 Token/秒 的服务提供商
    },
  },
  stream: false,
});

在此示例中，OpenRouter 会在这三个模型中找到 p90 吞吐量至少为每秒 50 Token 的最便宜模型与服务提供商（即 90% 的请求达到或超过该吞吐量）。低于该阈值的模型和服务提供商仍可作为回退：当所有优先选项都失败时，它们仍然可用。

你也可以使用 preferred_max_latency 设置可接受的最高延迟：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5-mini',
  ],
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: {
      by: 'price',
      partition: 'none',
    },
    preferredMaxLatency: {
      p90: 3, // 优先选择过去 5 分钟内 90% 的请求延迟 <3 秒 的服务提供商
    },
  },
  stream: false,
});

示例：使用多个百分位截止值

你可以指定多个百分位截止值，同时设置典型性能和最差情况性能要求。模型和该服务提供商必须同时满足所有指定的截止值，才会进入优先组。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'deepseek/deepseek-v3.2',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    preferredMaxLatency: {
      p50: 1, // 优先选择过去 5 分钟内 50% 的请求延迟 <1 秒 的服务提供商
      p90: 3, // 优先选择过去 5 分钟内 90% 的请求延迟 <3 秒 的服务提供商
      p99: 5, // 优先选择过去 5 分钟内 99% 的请求延迟 <5 秒 的服务提供商
    },
    preferredMinThroughput: {
      p50: 100, // 优先选择过去 5 分钟内 50% 的请求吞吐量 >100 Token/秒 的服务提供商
      p90: 50, // 优先选择过去 5 分钟内 90% 的请求吞吐量 >50 Token/秒 的服务提供商
    },
  },
  stream: false,
});

用例 3：跨模型最大化自带密钥（BYOK）用量

如果你使用自带密钥（Bring Your Own Key，BYOK），并希望尽量提高自有 API 密钥的用量，partition: "none" 会有帮助。当主模型没有可用的 BYOK 服务提供商时，OpenRouter 可以路由到支持 BYOK 的回退模型。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5-mini',
    'google/gemini-3-flash-preview',
  ],
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: {
      by: 'price',
      partition: 'none',
    },
  },
  stream: false,
});

在此示例中，如果你为 OpenAI 配置了 BYOK 密钥但未为 Anthropic 配置，即使 Claude 排在列表第一位，OpenRouter 也可以使用你自己的密钥将请求路由到 GPT-4o 端点。若不设置 partition: "none"，路由器会始终先尝试 Claude 的端点，然后再回退到 GPT-4o。

指定服务提供商顺序

你可以使用 order 字段设置 OpenRouter 为请求优先尝试的服务提供商。

对于你正在使用的模型，路由器会按该列表中的服务提供商及其顺序给予优先。如果未设置此字段，路由器会在领先的服务提供商之间负载均衡，以最大化可用性。

OpenRouter 会逐一尝试它们；如果全部不可用，再继续尝试其他服务提供商。如果你不想允许任何其他服务提供商，还应禁用回退。

示例：指定服务提供商并启用回退

此示例会跳过 OpenAI（它并不托管 Mixtral），尝试 Together，然后回退到 OpenRouter 上的常规服务提供商列表：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'mistralai/mixtral-8x7b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    order: ['openai', 'together'],
  },
  stream: false,
});

示例：指定服务提供商并禁用回退

下面这个将 allow_fallbacks 设为 false 的示例会跳过 OpenAI（它并不托管 Mixtral），尝试 Together，如果 Together 失败则请求失败：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'mistralai/mixtral-8x7b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    order: ['openai', 'together'],
    allowFallbacks: false,
  },
  stream: false,
});

定向到特定服务提供商端点

OpenRouter 上的每个服务提供商都可能为同一模型托管多个端点，例如默认端点和专用的 "turbo" 端点，或 google-vertex/us-east5 这类特定区域端点。若要定向到特定端点，可以在模型详情页服务提供商名称旁使用复制按钮，获取精确的服务提供商 slug。

基础 slug 匹配

当你在任意服务提供商路由字段（order、only 或 ignore）中使用基础服务提供商 slug（例如 "google-vertex"）时，它会匹配该服务提供商的所有端点，包括所有变体和区域。例如，"google-vertex" 会匹配 google-vertex、google-vertex/us-east5、google-vertex/us-central1 等。请注意，服务层级端点（例如 openai/priority、google-vertex/flex）不会被基础 slug 匹配——它们需要通过 service_tier 参数或带层级后缀的 slug 显式启用。

若要定向到特定变体或区域，请使用包含后缀的完整 slug（例如 "google-vertex/us-east5" 或 "deepinfra/turbo"）。

示例：定向到特定端点变体

例如，DeepInfra 通过多个端点提供 DeepSeek R1：

• 默认端点，slug 为 deepinfra
• Turbo 端点，slug 为 deepinfra/turbo

通过复制精确的服务提供商 slug 并将其放入请求的 order 数组，你可以确保请求被路由到你想要的特定端点：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'deepseek/deepseek-r1',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    order: ['deepinfra/turbo'],
    allowFallbacks: false,
  },
  stream: false,
});

当你希望始终使用来自特定服务提供商的某个模型变体时，这种方法尤其有用。

要求服务提供商支持全部参数

你可以使用 require_parameters 字段，将请求限制为仅发送给支持请求中全部参数的服务提供商。

在默认路由策略下，即使服务提供商不支持你请求中指定的全部 LLM 参数，仍可能收到该请求，但会忽略未知参数。当你将 require_parameters 设为 true 时，请求甚至不会被路由到该服务提供商。

示例：排除不支持 JSON 格式化的服务提供商

例如，若要仅使用支持 JSON 格式化的服务提供商：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    requireParameters: true,
  },
  responseFormat: { type: 'json_object' },
  stream: false,
});

要求服务提供商遵守数据策略

你可以使用 data_collection 字段，将请求限制为仅发送给符合你数据策略的服务提供商。

• allow：（默认）允许非瞬时存储用户数据并可能基于这些数据训练的服务提供商
• deny：仅使用不收集用户数据的服务提供商

部分模型服务提供商可能会记录提示词，因此我们会在模型页面上用**数据策略（Data Policy）**标签标示它们。这并非第三方数据策略的权威来源，而是我们目前掌握的最佳信息。

示例：排除不符合数据策略的服务提供商

若要排除不符合你数据策略的服务提供商，请将 data_collection 设为 deny：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    dataCollection: 'deny', // 或 "allow"
  },
  stream: false,
});

强制零数据保留

你可以使用 zdr 参数按请求强制零数据保留（ZDR），确保请求只路由到不保留提示词的端点。

当 zdr 设为 true 时，请求将只被路由到具有零数据保留策略的端点。当 zdr 为 false 或未提供时，它对路由没有影响。

示例：为特定请求强制 ZDR

若要确保请求只使用 ZDR 端点，请将 zdr 设为 true：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    zdr: true,
  },
  stream: false,
});

这适合不希望全局强制 ZDR、但需要确保特定请求只路由到 ZDR 端点的客户。

强制可蒸馏文本

你可以使用 enforce_distillable_text 参数按请求强制筛选可蒸馏文本，确保请求只路由到作者已允许文本蒸馏的模型。

当 enforce_distillable_text 设为 true 时，请求将只被路由到作者已显式启用文本蒸馏的模型。当 enforce_distillable_text 为 false 或未提供时，它对路由没有影响。

该参数适用于需要确保请求只使用允许将文本蒸馏用于训练的模型的应用，例如在构建用于模型微调或蒸馏工作流的数据集时。

示例：为特定请求强制可蒸馏文本

若要确保请求只使用允许文本蒸馏的模型，请将 enforce_distillable_text 设为 true：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.3-70b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    enforceDistillableText: true,
  },
  stream: false,
});

禁用回退

若要保证请求只由排名最高（成本最低）的服务提供商处理，可以禁用回退。

这可以与指定服务提供商顺序中的 order 字段结合使用，将 OpenRouter 优先考虑的服务提供商限制为你所选的列表。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    allowFallbacks: false,
  },
  stream: false,
});

仅允许特定服务提供商

你可以通过在 provider 对象中设置 only 字段，为某次请求仅允许特定服务提供商。

示例：调用 GPT-4 Omni 时仅允许 Azure

下面这个示例在调用 GPT-4 Omni 时将只使用 Azure：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'openai/gpt-5-mini',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    only: ['azure'],
  },
  stream: false,
});

忽略服务提供商

你可以通过在 provider 对象中设置 ignore 字段，为某次请求忽略特定服务提供商。

示例：调用 Llama 3.3 70b 时忽略 DeepInfra

下面这个示例在调用 Llama 3.3 70b 时将忽略 DeepInfra：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.3-70b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    ignore: ['deepinfra'],
  },
  stream: false,
});

量化

量化在力求保持性能的同时，减小模型体积并降低计算需求。如今大多数 LLM 使用 FP16 或 BF16 进行训练和推理，相比 FP32 可将内存需求减半。一些优化会使用 FP8 或量化进一步缩小体积（例如 INT8、INT4）。

服务提供商可以为开放权重模型支持多种量化级别。

量化级别

默认情况下，请求会在所有可用服务提供商之间按价格排序进行负载均衡。若要按量化级别筛选服务提供商，请在 provider 参数中指定 quantizations 字段，取值如下：

• int4：整数（4 位）
• int8：整数（8 位）
• fp4：浮点（4 位），包括 mxfp4 或 nvfp4
• mxfp4：微缩放浮点（4 位）
• nvfp4：NVIDIA 浮点（4 位）
• fp6：浮点（6 位）
• fp8：浮点（8 位），包括 mxfp8
• mxfp8：微缩放浮点（8 位）
• fp16：浮点（16 位）
• bf16：Brain 浮点（16 位）
• fp32：浮点（32 位）
• unknown：未知

示例：请求 FP8 量化

下面这个示例将只使用支持 FP8 量化的服务提供商：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  model: 'meta-llama/llama-3.1-8b-instruct',
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    quantizations: ['fp8'],
  },
  stream: false,
});

最高价格

若要按价格筛选服务提供商，请在 provider 参数中指定 max_price 字段，其值为一个 JSON 对象，表示你可接受的最高服务提供商定价。

例如，值 {"prompt": 1, "completion": 2} 会路由到提示词 Token 价格 <= $1/m、补全 Token 价格 <= $2/m 或更低的任何服务提供商。

部分服务提供商支持按请求计费，此时可以使用 max_price 的 request 属性。最后还有 image，用于指定你可接受的每张图片最高价格。

实际使用中，该字段常与服务提供商的 sort 组合，以表达例如「使用吞吐量最高的服务提供商，只要其价格不超过 $x/m Token」。

服务提供商专用请求头

部分服务提供商支持可通过特殊请求头启用的 Beta 功能。在发起请求时，OpenRouter 允许你透传某些服务提供商专用的 Beta 请求头。

Anthropic Beta 功能

使用 Anthropic 模型（Claude）时，你可以在请求中加入 x-anthropic-beta 请求头来请求特定 Beta 功能。OpenRouter 会将受支持的 Beta 功能透传给 Anthropic。

支持的 Beta 功能

示例：启用交错思考

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send(
  {
    model: 'anthropic/claude-sonnet-4.5',
    messages: [{ role: 'user', content: '逐步求解：240 的 15% 是多少？' }],
    stream: true,
  },
  {
    headers: {
      'x-anthropic-beta': 'interleaved-thinking-2025-05-14',
    },
  },
);

组合多个 Beta 功能

你可以用逗号分隔来同时启用多个 Beta 功能：

x-anthropic-beta: interleaved-thinking-2025-05-14,structured-outputs-2025-11-13

服务条款

你可以在下方查看各服务提供商的服务条款。你不得违反为 OpenRouter 上的模型提供支持的第三方服务提供商的服务条款或政策。