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