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

# 密钥模型许可列表

> 读取或替换某个密钥的模型许可列表（allowlist），用于限制该密钥可运行的 Theo 模型。

每个 API 密钥都可以携带一份显式的**模型许可列表**，其中包含以 Theo 品牌命名的模型 id（例如 `theo-1-flash`、`theo-1-reason`）。**空**许可列表表示该密钥继承所有模型（默认行为）。**非空**许可列表则会限制该密钥：任何解析到列表之外模型的请求都会被拒绝，返回 `403 model_not_allowed`——在原生端点和兼容 OpenAI 的端点上均是如此。

## 身份验证

需要具有 `billing` 权限范围的 API 密钥。调用方必须拥有该密钥（或是被允许管理密钥的团队成员）。

## 路径参数

<ParamField path="id" type="string" required>
  该 API 密钥的 UUID。
</ParamField>

## 获取许可列表

`GET /api/v1/keys/{id}/models`

<ResponseField name="key_id" type="string">该 API 密钥的 UUID。</ResponseField>
<ResponseField name="inherits_all" type="boolean">当许可列表为空时为 `true`（表示该密钥可以运行任意模型）。</ResponseField>
<ResponseField name="model_ids" type="string[]">允许使用的 Theo 模型 id 列表（当 `inherits_all` 为 `true` 时为空）。</ResponseField>

## 替换许可列表

`PUT /api/v1/keys/{id}/models`

<ParamField body="model_ids" type="string[]" required>
  要允许的完整 Theo 模型 id 集合（例如 `["theo-1-reason", "theo-1-code"]`）。传入空数组可将该密钥重置为继承所有模型。未知的 id 会被拒绝。
</ParamField>

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/models \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "model_ids": ["theo-1-reason", "theo-1-code"] }'
  ```

  ```ts SDK theme={null}
  // Model binding is set via the dashboard or this REST endpoint.
  // A request that resolves to a model outside the list throws TheoError(403, "model_not_allowed").
  ```
</CodeGroup>

```json theme={null}
{ "key_id": "KEY_ID", "inherits_all": false, "model_ids": ["theo-1-reason", "theo-1-code"] }
```


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