> ## 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.

# Model Access（模型访问）

## 模型访问

「模型访问」用于控制单个 API 密钥可以调用哪些模型。它不改变团队已开通的模型范围，只会在此范围内进一步收敛某个密钥可访问的模型。未包含在访问范围内的模型，调用时会被直接拒绝。

<Info>
  本能力覆盖大语言模型（LLM）产品线下的模型。图片、视频等独立多模态能力暂不纳入模型访问配置范围。
</Info>

常见的使用场景：

* **隔离不同用途的密钥**：让生产密钥只访问稳定模型，实验密钥只访问低成本模型。
* **应急收敛风险**：某个密钥出现非预期的高成本模型调用时，先把它限制到几个安全模型。
* **外部合作控制**：临时提供给外包或合作方的密钥，只开放约定的模型。

### 访问模式

每个 API 密钥有一种访问模式，二选一：

| 访问模式    | 含义                                                       |
| :------ | :------------------------------------------------------- |
| 全部已开通模型 | 默认模式。可访问团队当前及未来开通的可用模型，可以再手动排除部分模型。未来新开通的模型会自动可访问，除非被排除。 |
| 仅限指定模型  | 只能访问手动选定的模型。团队后续新开通的模型不会自动加入，需要手动添加。                     |

两种模式下，实际可访问的模型都遵循同一条边界：不能超出团队已开通的模型范围，也不包含已下线的模型。

* 全部已开通模型：可访问模型 = 团队已开通模型（含未来新开通模型）− 已排除的模型。
* 仅限指定模型：可访问模型 = 已选定的模型（与团队已开通模型取交集）。

### 配置模型访问

<Note>
  只有团队的管理员可以配置 API 密钥的模型访问。开发者和基础用户可以查看与自己相关密钥的只读摘要，但不能编辑；财务管理员看不到模型访问入口。
</Note>

<Steps>
  <Step title="进入 API 密钥管理页面">
    前往 <a href="https://ppio.com/settings/key-management" target="_blank">API 密钥管理页面</a>，找到要配置的 API 密钥。
  </Step>

  <Step title="打开模型访问设置">
    在创建或编辑该 API 密钥时，进入「模型访问」区域。
  </Step>

  <Step title="选择访问模式">
    选择「全部已开通模型」或「仅限指定模型」：

    * 选择「全部已开通模型」时，可在「已排除的模型」中添加需要禁止访问的模型。
    * 选择「仅限指定模型」时，在「可访问的模型」中至少添加一个模型。
  </Step>

  <Step title="保存">
    保存后，新的模型访问设置可能需要一段时间才会生效。
  </Step>
</Steps>

<Tip>
  在创建新密钥或编辑现有密钥时，可以通过「复制配置」「粘贴配置」复用同一 Team 内其他密钥的模型访问设置，粘贴后可直接保存，也可以调整后再保存。
</Tip>

### 模型下线的影响

<Warning>
  模型下线与 API 密钥权限限制是两种不同情况。模型下线后，所有 API 密钥都不能继续调用该模型；这不是某个密钥的「模型访问」配置问题。
</Warning>

如果某个模型被平台下线，该模型不再属于可用模型集合：

* 对该模型的所有调用会立即返回「模型不可用」，即使该 API 密钥此前有权限访问它。
* 历史配置中如果仍包含已下线模型，页面会保留展示并置灰提示；保存前必须先移除，否则不允许保存。

### 调用被拒的表现

<Warning>
  调用被拒时，请先根据 HTTP 状态码和错误码判断原因。`model_access_denied` 表示 API 密钥未被允许调用目标模型；模型下线则返回「模型不可用」，不属于密钥权限拒绝。
</Warning>

当 API 密钥调用了不在其访问范围内的模型时，调用会返回 HTTP 403 和错误码 `model_access_denied`，并提示该密钥不能访问此模型。此时请联系团队管理员调整该密钥的模型访问设置。

常见错误码的排查参见<a href="/docs/model/error">常见错误码说明</a>。

如果需要通过 API 自动化管理密钥的模型访问，参见 <a href="/docs/management/reference-key-get-model-access-policy">查询 API Key 模型访问策略</a>。