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 可選擇的模型範圍:
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 模型支援有限。
路由底層原理
1. 解析 model 欄位 → 提取提供商 ID
2. 檢查 API key 權限 → 該提供商是否被允許?
3. 呼叫路由服務 → 選擇區域,從池中挑選健康金鑰
4. 改寫 model 欄位 → 去除提供商前綴
5. 反向代理 → 使用提供商 API key 轉發至上游
6. 串流返回回應 → 非同步記錄用量
ARouter 完全透明地處理提供商 API key 注入、健康檢查和故障轉移。
您的應用程式永遠不會看到上游提供商的憑證。