模型路由

`provider/model` 格式

使用与 OpenAI 兼容的端点（/v1/chat/completions、/v1/embeddings）时，请使用 provider/model 格式指定模型：

{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [{"role": "user", "content": "Hello!"}]
}

ARouter 解析提供商前缀，将请求路由到正确的上游，并在转发前将 model 字段改写为提供商的原生格式。

示例

您发送	提供商	上游模型
`openai/gpt-5.4`	OpenAI	`gpt-5.4`
`anthropic/claude-sonnet-4.6`	Anthropic	`claude-sonnet-4.6`
`google/gemini-2.5-flash`	Google	`gemini-2.5-flash`
`deepseek/deepseek-v3.2`	DeepSeek	`deepseek-v3.2`
`x-ai/grok-4.20`	xAI	`grok-4.20`
`mistralai/mistral-large-2512`	Mistral	`mistral-large-2512`
`meta-llama/llama-4-maverick`	Meta	`llama-4-maverick`
`gpt-5.4`	OpenAI（默认）	`gpt-5.4`

如果省略提供商前缀，ARouter 默认使用 OpenAI。因此 "model": "gpt-5.4" 等同于 "model": "openai/gpt-5.4"。

原生 SDK 端点

对于拥有自己 SDK 格式的提供商，请直接使用原生端点。提供商由端点路径决定，而非 model 字段：

SDK	端点	模型格式
Anthropic	`POST /v1/messages`	原生：`claude-sonnet-4.6`
Gemini	`POST /v1beta/models/{model}:generateContent`	原生：`gemini-2.5-flash`
MiniMax	`POST /v1/text/chatcompletion_v2`	原生：`minimax-m2.7`

原生端点不使用 provider/model 前缀——它们使用提供商的原始模型名称，因为提供商已由端点路径隐含确定。

通用提供商代理

对于任何提供商，您也可以使用通用代理格式：

POST /{provider}/v1/chat/completions

例如：

POST /openai/v1/chat/completions → 代理至 OpenAI
POST /deepseek/v1/chat/completions → 代理至 DeepSeek
POST /anthropic/v1/messages → 代理至 Anthropic

当您想绕过 model 字段解析并明确控制哪个提供商接收请求时，此方式非常有用。

自动路由

将 model 设置为 "auto"，ARouter 将自动为您的提示选择最佳可用模型。无需任何模型配置。

{
  "model": "auto",
  "messages": [{ "role": "user", "content": "Explain quantum entanglement in simple terms" }]
}

工作原理

ARouter 的路由服务分析您的请求（提示复杂度、任务类型、所需模态等）
根据成本效率和质量，从健康的可用提供商中选出最优模型
将您的请求转发至所选模型
响应中包含 model 字段，显示实际使用的模型

限制可选模型

使用 auto-router 插件通过通配符模式限制 auto 可选择的模型范围：

TypeScript
Python
cURL

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Explain quantum entanglement" }],
  // @ts-ignore
  plugins: [
    {
      id: "auto-router",
      allowed_models: ["anthropic/*", "openai/gpt-5.4"],
    },
  ],
});

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Explain quantum entanglement"}],
    extra_body={
        "plugins": [
            {
                "id": "auto-router",
                "allowed_models": ["anthropic/*", "openai/gpt-5.4"],
            }
        ]
    },
)

curl https://api.arouter.ai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain quantum entanglement"}],
    "plugins": [
      {
        "id": "auto-router",
        "allowed_models": ["anthropic/*", "openai/gpt-5.4"]
      }
    ]
  }'

模式语法：

模式	匹配
`anthropic/*`	所有 Anthropic 模型
`openai/gpt-5*`	所有 GPT-5 变体
`google/*`	所有 Google 模型
`openai/gpt-5.4`	仅精确匹配
`/claude-`	任何提供商中模型名含 “claude” 的模型

{
  "id": "chatcmpl-xxx",
  "model": "anthropic/claude-sonnet-4.6",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 120,
    "total_tokens": 135
  }
}

请始终检查 response.model 以确认实际使用的模型。

代码示例

Python (OpenAI)
Node.js (OpenAI)
Go
cURL

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Explain quantum entanglement in simple terms"}],
)

print(response.choices[0].message.content)
print("Model used:", response.model)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Explain quantum entanglement in simple terms" }],
});

console.log(response.choices[0].message.content);
console.log("Model used:", response.model);

resp, err := client.CreateChatCompletion(ctx, arouter.ChatCompletionRequest{
    Model: "auto",
    Messages: []arouter.Message{
        {Role: "user", Content: "Explain quantum entanglement in simple terms"},
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Choices[0].Message.Content)
fmt.Println("Model used:", resp.Model)

curl https://api.arouter.ai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain quantum entanglement in simple terms"}]
  }'

使用场景

通用应用 — 当您不确定用户会发送哪类提示时
成本优化 — 让 ARouter 自动将简单任务路由到高效模型
零配置原型 — 无需选择特定模型即可快速上手
自适应路由 — 先让 ARouter 自动选择，仅在需要精确控制时再切换为有序候选列表

限制说明

自动路由使用标准 messages 请求格式
自动路由从您账户可用的模型中选择
流式传输完全支持 "model": "auto"
您按 ARouter 所选模型的正常费率付费，不收取额外路由费
所选模型始终体现在响应的 model 字段中

候选模型列表

将 models 数组与 route 结合使用，让 ARouter 按顺序遍历候选模型列表。

{
  "models": [
    "anthropic/claude-opus-4.5",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

工作原理

ARouter 尝试列表中的第一个模型
如果该模型无法处理请求（提供商错误、速率限制、密钥不可用），则切换到下一个
如果所有模型均失败，ARouter 返回含最后一次失败原因的错误

路由行为

触发条件	行为
提供商不可用	切换到下一个模型
速率限制（429）	切换到下一个模型
模型未找到	切换到下一个模型
错误请求（400）	停止并返回请求错误

控制分区行为

默认情况下，使用候选列表时，端点按模型分组——第一个模型的端点始终在第二个模型之前尝试。您可以通过 provider.sort.partition 更改此行为：

{
  "models": [
    "anthropic/claude-sonnet-4.6",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "provider": {
    "sort": {
      "by": "throughput",
      "partition": "none"
    }
  }
}

设置 partition: "none" 可在所有候选模型间全局排序端点——当您希望使用当前最快的模型而不关心列表顺序时非常有用。完整参考请参阅提供商路由。

在 OpenAI SDK 中使用候选列表

OpenAI SDK 原生不支持 models 参数。请使用 extra_body 传入：

Python (OpenAI)
Node.js (OpenAI)
cURL

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

response = client.chat.completions.create(
    model="anthropic/claude-opus-4.5",  # 第一候选
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "models": [
            "anthropic/claude-opus-4.5",
            "openai/gpt-5.4",
            "google/gemini-2.5-flash",
        ],
        "route": "fallback",
    },
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

const response = await client.chat.completions.create({
  model: "anthropic/claude-opus-4.5", // 第一候选
  messages: [{ role: "user", content: "Hello!" }],
  // @ts-ignore — extra_body 不在类型定义中
  models: [
    "anthropic/claude-opus-4.5",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash",
  ],
  route: "fallback",
});
console.log(response.choices[0].message.content);

curl https://api.arouter.ai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [
      "anthropic/claude-opus-4.5",
      "openai/gpt-5.4",
      "google/gemini-2.5-flash"
    ],
    "route": "fallback",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

助手预填充

ARouter 支持让模型补全部分响应。在 messages 数组末尾添加一条 role: "assistant" 的消息，即可从您留下的位置继续：

{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [
    { "role": "user", "content": "Name 3 popular programming languages." },
    { "role": "assistant", "content": "1." }
  ]
}

模型将从预填充的助手消息继续。此技术适用于：

强制特定输出格式
恢复多轮补全
引导模型生成特定响应结构

并非所有模型都支持助手预填充。Anthropic Claude 和大多数开源模型支持此功能。OpenAI 模型支持有限。

路由底层原理

解析 model 字段 → 提取提供商 ID
检查 API key 权限 → 该提供商是否被允许？
调用路由服务 → 选择区域，从池中挑选健康密钥
改写 model 字段 → 去除提供商前缀
反向代理 → 使用提供商 API key 转发至上游
流式返回响应 → 异步记录用量

ARouter 完全透明地处理提供商 API key 注入、健康检查和故障转移。您的应用程序永远不会看到上游提供商的凭据。

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

`provider/model` 格式

示例

原生 SDK 端点

通用提供商代理

自动路由

工作原理

限制可选模型

代码示例

使用场景

限制说明

候选模型列表

工作原理

路由行为

控制分区行为

在 OpenAI SDK 中使用候选列表

助手预填充

路由底层原理

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

​provider/model 格式

​示例

​原生 SDK 端点

​通用提供商代理

​自动路由

​工作原理

​限制可选模型

​代码示例

​使用场景

​限制说明

​候选模型列表

​工作原理

​路由行为

​控制分区行为

​在 OpenAI SDK 中使用候选列表

​助手预填充

​路由底层原理

`provider/model` 格式

示例

原生 SDK 端点

通用提供商代理

自动路由

工作原理

限制可选模型

代码示例

使用场景

限制说明

候选模型列表

工作原理

路由行为

控制分区行为

在 OpenAI SDK 中使用候选列表

助手预填充

路由底层原理