# API Key 精细化权限控制

## 简介

2026-03-20 新增 API Key 精细化权限控制功能，支持按额度、按模型、按IP白名单和标签维度进行权限控制。

> 注意：此功能为实验性功能，如需使用，请联系产品开通新平台权限。

### 标签管理

API Key 支持绑定一个或多个标签，便于按业务线、环境、应用等维度对 API Key 进行分类和筛选。标签绑定和解绑通过独立的标签管理接口完成，不需要修改 API Key 的创建或更新参数。

> 注意：标签管理接口属于管理 API，接口名称、请求地址和公共参数请以 API 管理平台发布的接口定义为准。

如需查看全部标签操作接口及其详细定义，请前往 [UCloud API 管理平台](https://console.ucloud.cn/uapi/ucloudapi/Cloud%20Resources) 查阅。

#### 标签数据结构

每个标签由标签键（`Key`）和标签值（`Value`）组成：

```json
{
  "Key": "environment",
  "Value": "production"
}
```

同一个 API Key 可以绑定多个标签。例如：

```json
[
  {
    "Key": "environment",
    "Value": "production"
  },
  {
    "Key": "application",
    "Value": "customer-service"
  }
]
```

#### 绑定标签

调用 `BindLabels` 接口时，传入项目 ID（`ProjectId`）、API Key 的资源 ID 列表（`ResourceIds`）以及需要绑定的标签列表（`Labels`）。绑定成功后，标签会保存到对应 API Key，并可在 API Key 列表中用于筛选。

请求示例：

```bash
curl 'https://api.ucloud.cn/?Action=BindLabels' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "ProjectId": "org-xxxx",
    "ResourceIds": [
      "uminferapikey-xxxxx"
    ],
    "Labels": [
      {
        "Key": "foo",
        "Value": "bar"
      }
    ],
    "Action": "BindLabels"
  }'
```

请求参数说明：

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `ProjectId` | `string` | 项目 ID。 |
| `ResourceIds` | `array[string]` | 待绑定标签的资源 ID 列表，填写 API Key 的资源 ID。 |
| `Labels` | `array[object]` | 要绑定的标签列表，每个标签包含 `Key` 和 `Value`。 |
| `Action` | `string` | API 操作名称，固定为 `BindLabels`。 |

#### 解绑标签

调用标签解绑接口时，传入 API Key 的资源 ID以及需要解绑的标签。解绑后，该标签不再与 API Key 关联；解绑全部标签后，API Key 恢复为无标签状态。解绑接口的具体名称、请求地址和参数请以 API 管理平台发布的接口定义为准。

#### 使用建议

- `ResourceIds` 中填写的是 API Key 的资源 ID（例如 `uminferapikey-xxxxx`），不是 API Key 密钥值。
- 标签键和值建议使用稳定、易维护的命名，例如 `environment`、`application`、`owner`。
- 绑定或解绑标签不会改变 API Key 的模型权限、额度、有效期或 IP 白名单配置。
- 删除 API Key 后，其关联标签也会一并失效。

## 功能说明

### 标签管理

API Key 支持绑定一个或多个标签，便于按业务线、环境、应用等维度对 API Key 进行分类和筛选。标签绑定和解绑通过独立的标签管理接口完成，不需要修改 API Key 的创建或更新参数。

> 注意：标签管理接口属于管理 API，接口名称、请求地址和公共参数请以 API 管理平台发布的接口定义为准。

如需查看全部标签操作接口及其详细定义，请前往 [UCloud API 管理平台](https://console.ucloud.cn/uapi/ucloudapi/Cloud%20Resources) 查阅。

#### 标签数据结构

每个标签由标签键（`Key`）和标签值（`Value`）组成：

```json
{
  "Key": "environment",
  "Value": "production"
}
```

同一个 API Key 可以绑定多个标签。例如：

```json
[
  {
    "Key": "environment",
    "Value": "production"
  },
  {
    "Key": "application",
    "Value": "customer-service"
  }
]
```

#### 绑定标签

调用 `BindLabels` 接口时，传入项目 ID（`ProjectId`）、API Key 的资源 ID 列表（`ResourceIds`）以及需要绑定的标签列表（`Labels`）。绑定成功后，标签会保存到对应 API Key，并可在 API Key 列表中用于筛选。

请求示例：

```bash
curl 'https://api.ucloud.cn/?Action=BindLabels' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "ProjectId": "org-xxxx",
    "ResourceIds": [
      "uminferapikey-xxxxx"
    ],
    "Labels": [
      {
        "Key": "foo",
        "Value": "bar"
      }
    ],
    "Action": "BindLabels"
  }'
```

请求参数说明：

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `ProjectId` | `string` | 项目 ID。 |
| `ResourceIds` | `array[string]` | 待绑定标签的资源 ID 列表，填写 API Key 的资源 ID。 |
| `Labels` | `array[object]` | 要绑定的标签列表，每个标签包含 `Key` 和 `Value`。 |
| `Action` | `string` | API 操作名称，固定为 `BindLabels`。 |

#### 解绑标签

调用标签解绑接口时，传入 API Key 的资源 ID以及需要解绑的标签。解绑后，该标签不再与 API Key 关联；解绑全部标签后，API Key 恢复为无标签状态。解绑接口的具体名称、请求地址和参数请以 API 管理平台发布的接口定义为准。

#### 使用建议

- `ResourceIds` 中填写的是 API Key 的资源 ID（例如 `uminferapikey-xxxxx`），不是 API Key 密钥值。
- 标签键和值建议使用稳定、易维护的命名，例如 `environment`、`application`、`owner`。
- 绑定或解绑标签不会改变 API Key 的模型权限、额度、有效期或 IP 白名单配置。
- 删除 API Key 后，其关联标签也会一并失效。

### 额度控制

API Key 支持设置 `每日` 或 `每月` 费用额度上限，超过上限后将无法继续调用API。额度可以在`创建/更新` API Key时设置。
> 注意：额度为可选配置，不配置时默认不限制费用额度。
>      额度限制以该key真实消费的费用为准，而非预估费用。（费用订单为后付费，每小时结算一次，因此额度限制可能存在一定的延迟，建议设置时预留一定的余量）
>      额度在费用结算后可能因扣费流程存在短暂的延迟。

#### 操作步骤如下

1. 登录控制台，进入API Key管理页面
2. 点击"创建API Key"或"编辑API Key"
3. 在"额度控制"区域，填写"每日"或"每月"额度上限
4. 点击"创建"按钮或"保存"按钮

![额度控制](https://static.ucloud.cn/docs/modelverse/images/api-doc/api-key-amount.png)
![额度控制](https://static.ucloud.cn/docs/modelverse/images/api-doc/api-key-amount-2.png)

#### 调用示例

```bash
curl https://api.modelverse.cn/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"Access forbidden: api key quota exceeded, key_id=uminferapikey-1j3gwjgyhkwc, daily_limit_amount=100 , monthly_limit_amount=1000","type":"permission_error","param":"c2ad1049-66a6-4640-b2b5-1711dc401092","code":"forbidden"}}
```

### 模型控制

API Key 支持设置可调用的模型列表，仅可调用列表中的模型。模型可以在`创建/更新` API Key时设置。
> 注意：模型控制为可选配置，不配置时默认可调用所有模型。
>      页面选择支持按照供应商等选择模型，但是不支持新增模型自动添加到列表中。如需添加新模型，需要手动添加。

> 例：创建 API Key 时，勾选全部OpenAI模型为可调用模型，在此时间点后推出新模型，该API Key仍无法调用新模型。如需调用新模型，需要更新API Key的可调用模型列表。

![模型控制](https://static.ucloud.cn/docs/modelverse/images/api-doc/api-key-model.png)

#### 调用示例

```bash
 curl https://api.modelverse.cn/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"No permission to use the model: apikey [uminferapikey-1j3gwjgyhkwc] not support model [deepseek-v4-pro]","type":"invalid_request_error","param":"6d7248f8-ebaa-437e-bfc2-d79e7c54004c","code":"model_error"}}
```
### IP白名单控制

API Key 支持设置可调用的IP白名单，未设置时可从任意IP使用该API Key调用API，设置后仅可从IP白名单中的IP调用API。IP白名单可以在`创建/更新` API Key时设置。

> 注意：IP白名单为可选配置，不配置时默认可从任意IP使用该API Key调用API。当前仅支持IPv4地址。
>      支持IP和网段格式，如 `192.168.1.1`、`192.168.1.0/24`、`192.168.1.10-192.168.1.20`。

![IP白名单控制](https://static.ucloud.cn/docs/modelverse/images/api-doc/api-key-ip.png)

#### 调用示例

```bash
 curl https://api.modelverse.cn/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"Access forbidden: api key ip not in whitelist, key_id=uminferapikey-1j3gwjgyhkwc, ip=127.0.0.1","type":"permission_error","param":"c2ad1049-66a6-4640-b2b5-1711dc401092","code":"forbidden"}}
```