模型路由

`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 中使用候選清單

助手預填充

路由底層原理