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

# 设置 API Key 模型访问策略

设置或更新单个 API Key 的模型访问策略。请求体直接传 `policy` 对象。

## 权限

仅团队的 Owner / Admin 可以调用。Developer、基础用户和财务管理员无权设置。被设置的 API Key 必须属于当前调用方所在的团队。

## 请求头

<ParamField header="Content-Type" type="string" required={true}>
  枚举值：`application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。
</ParamField>

## 路径参数

<ParamField path="stringId" type="string" required={true}>
  目标 API Key 的 stringId。
</ParamField>

## 请求体

<ParamField body="schemaVersion" type="int32" required={false}>
  策略结构版本号，当前为 `1`。
</ParamField>

<ParamField body="productScope" type="string" required={false}>
  策略适用的产品范围。传入时仅支持 `model_api`。
</ParamField>

<ParamField body="mode" type="string" required={true}>
  访问模式。取值：`all_enabled`（可访问全部已开通模型）、`selected`（仅可访问指定模型）。
</ParamField>

<ParamField body="allowedModels" type="object[]" required={false}>
  可访问的模型列表。`mode=selected` 时必填，且至少包含一个模型；`mode=all_enabled` 时会被忽略。

  <Expandable title="properties">
    <ParamField body="type" type="string" required={true}>
      模型类型。取值：`llm`、`multimodal`。
    </ParamField>

    <ParamField body="id" type="string" required={true}>
      模型标识，例如 `deepseek/deepseek-v3`。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="excludedModels" type="object[]" required={false}>
  已排除的模型列表。`mode=all_enabled` 时生效；`mode=selected` 时会被忽略。字段结构同 `allowedModels`。
</ParamField>

<Note>
  写入约束：

  * `mode` 必须是 `all_enabled` 或 `selected`。
  * `mode=selected` 时，`allowedModels` 至少包含一个模型。
  * 写入的模型必须属于该团队已开通的模型范围且当前可用；包含已下线、不可用或团队未开通的模型时，请求会被拒绝。
  * 未参与当前模式计算的模型数组会被规范化为空；重复的模型会被去重。返回结果以服务端规范化后的对象为准。
  * `source` 由服务端管理，写入时忽略。
</Note>

## 响应

返回结构与<a href="/docs/management/reference-key-get-model-access-policy">查询 API Key 模型访问策略</a>一致，为规范化后的最新策略对象。

<RequestExample>
  ```bash 仅指定模型 theme={null}
  curl --request PUT \
    --url https://api.ppio.com/openapi/v2/user/key/<stringId>/model-access-policy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "selected",
      "allowedModels": [
        { "type": "llm", "id": "deepseek/deepseek-v3" }
      ]
    }'
  ```

  ```bash 全部已开通模型 theme={null}
  curl --request PUT \
    --url https://api.ppio.com/openapi/v2/user/key/<stringId>/model-access-policy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "all_enabled"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "stringId": "key_xxx",
    "policy": {
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "selected",
      "allowedModels": [
        {
          "type": "llm",
          "id": "deepseek/deepseek-v3"
        }
      ],
      "excludedModels": [],
      "source": {
        "type": "private_policy"
      }
    },
    "policyStatus": "active",
    "allowedModelCount": 1,
    "excludedModelCount": 0,
    "updatedAt": 1783764000,
    "updatedBy": "user_uuid_xxx"
  }
  ```
</ResponseExample>