跳轉到主要內容

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.4OpenAIgpt-5.4
anthropic/claude-sonnet-4.6Anthropicclaude-sonnet-4.6
google/gemini-2.5-flashGooglegemini-2.5-flash
deepseek/deepseek-v3.2DeepSeekdeepseek-v3.2
x-ai/grok-4.20xAIgrok-4.20
mistralai/mistral-large-2512Mistralmistral-large-2512
meta-llama/llama-4-maverickMetallama-4-maverick
gpt-5.4OpenAI(預設)gpt-5.4
如果省略提供商前綴,ARouter 預設使用 OpenAI。 因此 "model": "gpt-5.4" 等同於 "model": "openai/gpt-5.4"

原生 SDK 端點

對於擁有自己 SDK 格式的提供商,請直接使用原生端點。 提供商由端點路徑決定,而非 model 欄位:
SDK端點模型格式
AnthropicPOST /v1/messages原生:claude-sonnet-4.6
GeminiPOST /v1beta/models/{model}:generateContent原生:gemini-2.5-flash
MiniMaxPOST /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" }]
}

運作原理

  1. ARouter 的路由服務分析您的請求(提示複雜度、任務類型、所需模態等)
  2. 根據成本效率和品質,從健康的可用提供商中選出最優模型
  3. 將您的請求轉發至所選模型
  4. 回應中包含 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"],
    },
  ],
});
模式語法:
模式匹配
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 以確認實際使用的模型。

程式碼範例

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)

使用場景

  • 通用應用 — 當您不確定使用者會傳送哪類提示時
  • 成本最佳化 — 讓 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!" }]
}

運作原理

  1. ARouter 嘗試清單中的第一個模型
  2. 如果該模型無法處理請求(提供商錯誤、速率限制、金鑰不可用),則切換到下一個
  3. 如果所有模型均失敗,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 傳入:
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)

助手預填充

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 注入、健康檢查和故障轉移。 您的應用程式永遠不會看到上游提供商的憑證。