跳到主要内容

提供商路由

最佳提供商路由请求

OpenRouter 会将请求路由到适合您模型的最佳可用提供商。默认情况下,请求会在顶级提供商之间进行负载均衡,以最大限度地延长正常运行时间。

您可以使用聊天生成输出生成请求主体中provider提供商对象自定义请求的路由方式。

提示

有关API中使用的有效提供商名称完整列表,请参阅完整提供商模式。

provider提供商对象包含以下字段:

字段类型默认描述
orderstring[]-按排序请求的提供商名称列表 (示例:["Anthropic", "OpenAI"]详细了解
allow_fallbacksbooleantrue当主提供程序不可用时是否允许备份提供商 详细了解
require_parametersbooleanfalse仅使用支持请求中所有参数的提供商 详细了解
data_collection”allow”“deny""allow”
ignorestring[]-此请求要跳过的提供商名称列表 详细了解
quantizationsstring[]-要过滤的量化级别列表 (示例:["int4", "int8"]). 详细了解
sortstring-按价格或吞吐量对供应商进行排序 (e.g. "price" or "throughput"). 详细了解

基于价格的负载均衡(默认策略)

对于请求中的每个模型,OpenRouter 默认行为是跨提供商对请求进行负载均衡,并优先考虑价格。

如果您对吞吐量比价格更敏感,可以使用 sort 字段明确地优先考虑吞吐量。

提示

当您发送带有 toolstool_choice 的请求时,OpenRouter 将仅路由到支持调用工具的提供商。同样,如果您设置了 max_tokens,OpenRouter 将仅路由到支持该长度响应的提供商。

OpenRouter 的默认负载均衡策略如下:

  1. 优先考虑过去 30 秒内未出现严重中断的提供商。
  2. 对于稳定的提供商,请查看成本最低的候选方案,并按价格平方反比加权选择一个(如下例所示)。
  3. 其余提供商作为备用方案。
信息

负载均衡示例

如果提供商 A 每百万Token的成本为 1 美元,提供商 B 的成本为 2 美元,提供商 C 的成本为 3 美元,并且提供商 B 最近出现了几次中断。

  • 您的请求被路由到提供商 A,被路由到提供商 A 的可能性是提供商 C 的 9 倍,因为(1/32=1/91/3^2 =1/9) (价格平方反比)。
  • 如果提供商 A 失败,则接下来将尝试提供商 C。
  • 如果提供商 C 也失败,则最后尝试提供商 B。

如果您在提供商首选项中设置了sortorder,则负载均衡将被禁用。

提供商排序

如上所述,OpenRouter 根据价格进行负载均衡,同时考虑正常运行时间。

如果您想明确优先考虑特定提供商属性,可以在provider提供商首选项中添加sort字段。负载均衡将被禁用,路由器将按顺序请求提供商。

三种排序选项如下:

  • price:优先考虑价格最低的提供商
  • throughput:优先考虑吞吐量最高的提供商
  • latency:优先考虑延迟最低的提供商
fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'anthropic/claude-3.7-sonnet',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'sort': 'throughput'
}
}),
});

始终优先考虑低价,且不应用任何负载均衡,请将sort设置为price

始终优先考虑低延迟,并且不应用任何负载均衡,请将sort设置为latency

Nitro 变体

您可将 :nitro 添加到任何模型后缀中,作为按吞吐量排序的快捷方式。这完全等同于将 provider.sort 设置为throughput

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'anthropic/claude-3.7-sonnet:nitro',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
]
}),
});

Floor 变体

您可以将 :floor 添加到任何模型后缀中,作为按价格排序的快捷方式。这完全等同于将 provider.sort 设置为 price

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'anthropic/claude-3.7-sonnet:floor',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
]
}),
});

指定提供商排序

您可以使用 order 字段设置 OpenRouter 将优先处理您的请求的提供商。

字段类型默认描述
orderstring[]-按排序请求的提供商名称列表 (示例:["Anthropic", "OpenAI"])

路由器将根据您使用的型号,按此排序优先选择此列表中的提供商。如果您未设置此字段,路由器将在排名靠前的提供商之间进行负载均衡,以最大限度地延长正常运行时间。

OpenRouter 将逐一尝试请求这些提供商,如果没有可运行的提供商,则继续尝试其他提供商。如果您不想允许任何其他提供商,应禁用回退功能。

示例:指定具有后备回退功能的提供商

此示例跳过 OpenAI(不托管 Mixtral),尝试请求 Together,然后回退到 OpenRouter 上的正常提供商列表:

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'mistralai/mixtral-8x7b-instruct',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'order': [
'OpenAI',
'Together'
]
}
}),
});

示例:指定禁用后备回退的提供商

下面是一个将 allow_fallbacks 设置为 false 的示例,它会跳过 OpenAI(不托管 Mixtral),尝试请求 Together,如果 Together 请求失败,它也会返回请求失败:

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'mistralai/mixtral-8x7b-instruct',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'order': [
'OpenAI',
'Together'
],
'allow_fallbacks': false
}
}),
});

要求提供商支持所有参数(测试版)

您可以使用 require_parameters 字段将请求限制为仅支持请求中所有参数的提供商。

字段类型默认描述
require_parametersbooleanfalse仅使用支持请求中所有参数的提供商

使用默认路由策略,不支持请求中指定的所有 LLM 参数的提供商仍然可以接收请求,但会忽略未知参数。当您将 require_parameters 设置为 true 时,请求甚至不会被路由到该提供商。

示例:排除不支持 JSON 格式的提供商

例如,仅使用支持 JSON 格式的提供商:

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'require_parameters': true
},
'response_format': {
'type': 'json_object'
}
}),
});

要求提供商遵守数据政策

您可以使用 data_collection 字段将请求限制为仅符合您的数据政策的提供商。

字段类型默认描述
data_collectionallowdenyallow控制是否使用可能存储数据的提供商
  • allow:(默认)允许非临时存储用户数据并可对其进行训练的提供商
  • deny:仅使用不收集用户数据的提供商

某些模型提供商可能会记录提示词,因此我们会在模型页面上显示带有“数据政策”标签的提示。这并非第三方数据政策的权威来源,但代表了我们的最佳认知。

示例:排除数据政策之外的提供商

要排除不符合数据政策的提供商,请将 data_collection 设置为 deny

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'data_collection': 'deny'
}
}),
});

禁用后备回退

为了确保您的请求仅由顶级(成本最低)提供商提供服务,您可以禁用回退功能。

此功能与指定提供商排序中的 order 字段相结合,将 OpenRouter 优先考虑的提供商限制为您选择的列表。

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'allow_fallbacks': false
}
}),
});

忽略提供商

要忽略提供商请求,您可通过在 provider 对象中设置 ignore 字段。

字段类型默认描述
ignorestring[]-针对此请求要跳过的提供商名称列表
提醒

忽略多个提供商可能会显著减少回退选项并限制请求恢复

示例:忽略 Azure 中调用 GPT-4o 请求

以下是一个示例,它将忽略 Azure 中调用 GPT-4o 的请求:

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'openai/gpt-4o',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'ignore': [
'Azure'
]
}
}),
});

量化

量化旨在保持性能同时降低模型尺寸大小和计算需求,目前大多数 LLM 使用 FP16 或 BF16 进行训练和推理,与 FP32 相比,内存需求减少了一半。一些优化使用 FP8 或量化来进一步减小模型大小(例如 INT8、INT4)。

字段类型默认描述
quantizationsstring[]-要过滤的量化级别列表(例如:["int4", "int8"])
提醒

根据所使用的方法,量化模型对于某些提示词的性能可能会下降。

提供商可以支持开放权重模型的各种量化级别。

量化级别

默认情况下,请求会在所有可用提供商之间进行负载均衡,并按价格排序。如需按量化级别筛选提供商,请在 provider 参数中指定以下值的quantizations字段:

  • int4:整数(4 位)
  • int8:整数(8 位)
  • fp4:浮点数(4 位)
  • fp6:浮点数(6 位)
  • fp8:浮点数(8 位)
  • fp16:浮点数(16 位)
  • bf16:Brain 浮点数(16 位)
  • fp32:浮点数(32 位)
  • unknown:未知

示例:请求 FP8 量化

以下是仅使用支持 FP8 量化的提供商示例:

fetch('https://openrouter.co/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
'model': 'meta-llama/llama-3.1-8b-instruct',
'messages': [
{
'role': 'user',
'content': 'Hello'
}
],
'provider': {
'quantizations': [
'fp8'
]
}
}),
});

服务条款

您可以查看下方各提供商的服务条款。您需遵循 OpenRouter 上模型支持的第三方提供商的服务条款或政策。

提供商首选项的 JSON 模式

有关选项的完整列表,请参阅此 JSON 模式:

{
"$ref": "#/definitions/Provider Preferences Schema",
"definitions": {
"Provider Preferences Schema": {
"type": "object",
"properties": {
"allow_fallbacks": {
"type": [
"boolean",
"null"
],
"description": "Whether to allow backup providers to serve requests\n- true: (default) when the primary provider (or your custom providers in \"order\") is unavailable, use the next best provider.\n- false: use only the primary/custom provider, and return the upstream error if it's unavailable.\n"
},
"require_parameters": {
"type": [
"boolean",
"null"
],
"description": "Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest."
},
"data_collection": {
"anyOf": [
{
"type": "string",
"enum": [
"deny",
"allow"
]
},
{
"type": "null"
}
],
"description": "Data collection setting. If no available model provider meets the requirement, your request will return an error.\n- allow: (default) allow providers which store user data non-transiently and may train on it\n- deny: use only providers which do not collect user data.\n"
},
"order": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"OpenAI",
"Anthropic",
"Google",
"Google AI Studio",
"Amazon Bedrock",
"Groq",
"SambaNova",
"Cohere",
"Mistral",
"Together",
"Together 2",
"Fireworks",
"DeepInfra",
"Lepton",
"Novita",
"Avian",
"Lambda",
"Azure",
"Modal",
"AnyScale",
"Replicate",
"Perplexity",
"Recursal",
"OctoAI",
"DeepSeek",
"Infermatic",
"AI21",
"Featherless",
"Inflection",
"xAI",
"Cloudflare",
"SF Compute",
"Minimax",
"Nineteen",
"Liquid",
"Stealth",
"NCompass",
"InferenceNet",
"Friendli",
"AionLabs",
"Alibaba",
"Nebius",
"Chutes",
"Kluster",
"Crusoe",
"Targon",
"Ubicloud",
"Parasail",
"Phala",
"Cent-ML",
"Venice",
"OpenInference",
"Atoma",
"01.AI",
"HuggingFace",
"Mancer",
"Mancer 2",
"Hyperbolic",
"Hyperbolic 2",
"Lynn 2",
"Lynn",
"Reflection"
]
}
},
{
"type": "null"
}
],
"description": "An ordered list of provider names. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message."
},
"ignore": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"OpenAI",
"Anthropic",
"Google",
"Google AI Studio",
"Amazon Bedrock",
"Groq",
"SambaNova",
"Cohere",
"Mistral",
"Together",
"Together 2",
"Fireworks",
"DeepInfra",
"Lepton",
"Novita",
"Avian",
"Lambda",
"Azure",
"Modal",
"AnyScale",
"Replicate",
"Perplexity",
"Recursal",
"OctoAI",
"DeepSeek",
"Infermatic",
"AI21",
"Featherless",
"Inflection",
"xAI",
"Cloudflare",
"SF Compute",
"Minimax",
"Nineteen",
"Liquid",
"Stealth",
"NCompass",
"InferenceNet",
"Friendli",
"AionLabs",
"Alibaba",
"Nebius",
"Chutes",
"Kluster",
"Crusoe",
"Targon",
"Ubicloud",
"Parasail",
"Phala",
"Cent-ML",
"Venice",
"OpenInference",
"Atoma",
"01.AI",
"HuggingFace",
"Mancer",
"Mancer 2",
"Hyperbolic",
"Hyperbolic 2",
"Lynn 2",
"Lynn",
"Reflection"
]
}
},
{
"type": "null"
}
],
"description": "List of provider names to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request."
},
"quantizations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"int4",
"int8",
"fp4",
"fp6",
"fp8",
"fp16",
"bf16",
"fp32",
"unknown"
]
}
},
{
"type": "null"
}
],
"description": "A list of quantization levels to filter the provider by."
},
"sort": {
"anyOf": [
{
"type": "string",
"enum": [
"price",
"throughput",
"latency"
]
},
{
"type": "null"
}
],
"description": "The sorting strategy to use for this request, if \"order\" is not specified. When set, no load balancing is performed."
}
},
"additionalProperties": false
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}