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

# 更新 Devin Desktop 模型允许列表

> 以编程方式替换您团队的 Devin Desktop 模型允许列表：设置允许的模型 UID 和标签，并通过 ETag 对照当前状态进行检查。

## 概述

替换您的团队的模型允许列表，该设置与 Admin 在 Devin Desktop 组织控制项中管理的设置相同。请求体即完整的目标状态：其中的两个列表会覆盖已存储的列表。

为避免覆盖你尚未看到的变更，请求必须在 `If-Match` 中携带 [List Models](/zh/desktop/accounts/api-reference/list-models) 响应返回的 `ETag`。如果在该响应之后，允许列表、可用模型或模型价格发生了变化，更新将被拒绝并返回 `412`，此时你需要重新列出模型。

> [!NOTE]
>
> 此端点处于 alpha 阶段 (`v2alpha`) ，请求和响应的结构可能会有所变化。

## 身份验证

在 `Authorization` 标头中传入 API 密钥：

```
Authorization: Bearer <api-key>
```

使用 Devin [服务用户 API 密钥](/zh/api-reference/authentication) (`cog_...`) 。除了 [List Models](/zh/desktop/accounts/api-reference/list-models) 所需的 **Use Devin Desktop** 权限外，服务用户的角色还必须具有 **Windsurf admin** 权限 (`account.windsurf.admin`) ，内置的 Account Admin 角色已包含此权限。缺少该权限的服务用户虽然可以列出模型，但调用此端点时会返回 `403`。

## 请求

**If-Match** `string` *required*

`GET /api/v2alpha/models` 响应中的 `ETag` 标头，用于反映当前状态。必填；不接受 `*`。

**allowed\_model\_uids** `string[]` *required*

用户可选择的模型 UID，例如 `["claude-sonnet-4-5"]`。传入 `[]` 表示仅按标签允许模型。

**allowed\_model\_tags** `string[]` *required*

用户可选择的模型标签，包括 `provider-anthropic`、`provider-openai` 等提供商标签。传入 `[]` 表示仅允许所列的模型 UID。

这两个字段均为必填。包含未知字段的请求将被拒绝。

### 请求示例

```bash theme={null}
ETAG=$(curl -s -D - -o /dev/null https://server.codeium.com/api/v2alpha/models \
  -H "Authorization: Bearer $DEVIN_API_KEY" | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')

curl -X PUT https://server.codeium.com/api/v2alpha/models \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{"allowed_model_uids": ["claude-sonnet-4-5"], "allowed_model_tags": ["provider-anthropic"]}'
```

## 响应

成功时，返回的响应与 [List Models](/zh/desktop/accounts/api-reference/list-models) 相同，并已应用新的允许列表：包含每个模型及其 `allowed` 开关、已存储的 `allowed_model_uids` 和 `allowed_model_tags`，以及新的 `ETag` 标头。

## 错误响应

错误以 `{"error": "<message>"}` 格式返回。

| 状态 | 原因 |
| - | - |
| `400` | 请求体不是 JSON、包含未知字段，或缺少 `allowed_model_uids` 或 `allowed_model_tags`；或设置了 `filter` 查询参数 (仅 [List Models](/zh/desktop/accounts/api-reference/list-models) 接受该参数) |
| `401` | 缺少 API 密钥或 API 密钥无效，或使用了旧版 Windsurf API 密钥 (仅接受 Devin `cog_...` 服务用户密钥) |
| `403` | 该密钥所属用户没有 Devin Desktop 访问权限，或其角色缺少 Windsurf admin 权限 (`account.windsurf.admin`) |
| `412` | `If-Match` 与当前 `ETag` 不匹配；请重新列出模型后重试 |
| `428` | 缺少 `If-Match` 标头 |
| `429` | 超出速率限制；请等待 `Retry-After` 标头指定的时间后再重试 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.