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

# Router Provider 列表与 upsert 接口

> 列出咏唱引擎 ROUTER 中全部已配置的 provider，或 upsert 一个 provider 规格。PUT 更新需要管理员权限。

使用 Provider 接口列出全部已配置的推理 provider，或创建并更新单个 provider 规格。GET 返回完整的 provider 集合。PUT 按标识符 upsert 一个 provider。只有管理员调用者可以修改 provider。

当你需要轮换后端引用、新增模型，或在不替换整个 router 配置的情况下接入新的 provider 时，此接口非常有用。

## 接口

```http theme={null}
GET /v1/router/providers
```

```http theme={null}
PUT /v1/router/providers
```

## 认证

使用会话 Cookie 认证，或携带 `Authorization: Bearer <api-key>`。PUT 方法需要管理员角色。

## GET 响应

<ResponseField name="items" type="array">
  已配置 provider 的列表。

  <Expandable title="items">
    <ResponseField name="name" type="string">
      唯一的 provider 标识符。
    </ResponseField>

    <ResponseField name="default_model" type="string">
      未指定模型时的回退模型。
    </ResponseField>

    <ResponseField name="models" type="array">
      此 provider 的模型定义。

      <Expandable title="items">
        <ResponseField name="name" type="string">
          模型名称。
        </ResponseField>

        <ResponseField name="backend_ref" type="string">
          后端端点或标识符。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## PUT 请求体

<ParamField body="name" type="string" required>
  唯一的 provider 标识符。
</ParamField>

<ParamField body="default_model" type="string">
  客户端未选择模型时的回退模型。
</ParamField>

<ParamField body="models" type="array">
  带后端引用的模型定义列表。
</ParamField>

## PUT 响应

<ResponseField name="name" type="string">
  被 upsert 的 provider 的标识符。
</ResponseField>

<ResponseField name="updated" type="boolean">
  该 provider 是被更新（`true`）还是被创建（`false`）。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # 列出 provider
  curl -X GET "https://router.example.com/v1/router/providers" \
    -H "Authorization: Bearer <api-key>"

  # upsert 一个 provider（仅管理员）
  curl -X PUT "https://router.example.com/v1/router/providers" \
    -H "Authorization: Bearer <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "openai",
      "default_model": "gpt-4o",
      "models": [
        {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"},
        {"name": "gpt-4o-mini", "backend_ref": "openai/gpt-4o-mini"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "items": [
      {
        "name": "openai",
        "default_model": "gpt-4o",
        "models": [
          {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"},
          {"name": "gpt-4o-mini", "backend_ref": "openai/gpt-4o-mini"}
        ]
      },
      {
        "name": "anthropic",
        "default_model": "claude-3-5-sonnet-20241022",
        "models": [
          {"name": "claude-3-5-sonnet-20241022", "backend_ref": "anthropic/claude-3-5-sonnet"}
        ]
      }
    ]
  }
  ```
</ResponseExample>