> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider 路由

Sunra 默认会把 canonical 模型 ID 自动路由到可用的服务商。大多数请求不需要传入 `provider`。

```json theme={null}
{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}
```

需要指定服务商或控制候选服务商范围时，可以传入可选的 `provider` 对象。Chat Completions、Messages、Responses 和 Embeddings 都支持 Provider 路由。

## 查询可用 Provider

不同模型和 API 格式支持的 Provider 可能不同。应用展示 Provider 选项前，可以调用查询接口：

```bash theme={null}
curl "https://api-llm.sunra.ai/v1/models/google/gemini-2.5-flash/providers?format=chat%2Fcompletions" \
  -H "Authorization: Bearer <SUNRA_KEY>"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "google-vertexai",
      "name": "Google Vertex AI",
      "supported_formats": ["chat/completions", "messages", "responses"]
    },
    {
      "id": "openrouter",
      "name": "OpenRouter",
      "supported_formats": ["chat/completions", "messages", "responses"]
    }
  ]
}
```

该查询接口与 LLM 推理接口使用相同的 API 密钥认证。`format` 支持 `chat/completions`、`messages`、`responses` 和 `embeddings`。

## 指定一个 Provider

通过 `provider.only` 把请求限制到指定 Provider：

```bash theme={null}
curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "provider": {
      "only": ["google-vertexai"]
    },
    "messages": [
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'
```

如果指定的 Provider 都无法支持该模型和 API 格式，请求会返回错误。

## 设置优先顺序

使用 `order` 按顺序指定优先 Provider。除非将 `allow_fallbacks` 设置为 `false`，未列入 `order` 的 Provider 仍可作为候选。

```json theme={null}
{
  "provider": {
    "order": ["google-vertexai", "openrouter"],
    "allow_fallbacks": false
  }
}
```

`allow_fallbacks` 只控制请求开始时的候选 Provider 范围，不表示上游已经返回响应或失败后会自动切换 Provider 重试。

## 排除 Provider

使用 `ignore` 从自动路由候选中排除 Provider：

```json theme={null}
{
  "provider": {
    "ignore": ["openrouter"]
  }
}
```

## 优先最低价格

使用 `sort: "price"` 优先选择价格最低的可用路由。只有省略 `order` 时才应用价格排序。

```json theme={null}
{
  "provider": {
    "sort": "price"
  }
}
```

当前尚不支持按 `latency` 或 `throughput` 排序。

## Provider 参数

<ParamField body="provider" type="object">
  可选的路由偏好。省略该对象时使用自动路由。

  <Expandable title="属性">
    <ParamField body="only" type="string[]">
      仅允许使用这些 Provider ID。
    </ParamField>

    <ParamField body="order" type="string[]">
      按顺序优先选择这些 Provider。
    </ParamField>

    <ParamField body="ignore" type="string[]">
      从路由候选中排除这些 Provider。
    </ParamField>

    <ParamField body="allow_fallbacks" type="boolean">
      存在 `order` 时，是否允许未列入 `order` 的 Provider 继续作为候选。默认为 `true`。
    </ParamField>

    <ParamField body="sort" type="string">
      对候选 Provider 排序。当前支持的值为 `price`。
    </ParamField>
  </Expandable>
</ParamField>