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

# 密鑰模型方案

> 讀取或替換某個密鑰的模型方案 —— 單模型鎖定和/或按模式的引擎綁定。

模型方案控制着**該密鑰運行哪個上游引擎**。有兩個相互獨立的調節項：

* **`single_model`** —— 為每一次文本輪次鎖定同一個引擎。這是一種確定性的直通模式，會跳過分類器（非常適合編碼 / IDE 後端場景，也包括 [自帶模型（BYO）](/api-reference/custom-providers/manage) 的 `custom:` 引擎）。
* **`bindings`** —— 將各個模式重新映射到指定引擎；分類器依然負責路由，但每個模式所使用的引擎是被鎖定的。

引擎 id 採用真實的上游 id（這是一個配置層面的入口）：`arca-velox-5.1`、`arca-magnus-5.1`、`anthropic/claude-sonnet-4.6`、`anthropic/claude-opus-4.8`、`anthropic/claude-haiku-4.5`、`google/gemini-2.5-pro`、`openai/gpt-4.1`，或者你自己的 `custom:<providerId>:<model>`。

<Note>如果需要完整的可運行流程（分支、護欄節點、路由），請改用 [編排器圖](/api-reference/keys/orchestrator-graph) —— 它的優先級高於模型方案。</Note>

## 身份驗證

需要具備 `billing` 權限範圍的 API 密鑰；調用者必須是該密鑰的所有者。

## 路徑參數

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

## 獲取方案

`GET /api/v1/keys/{id}/model-plan`

<ResponseField name="single_model" type="object | null">被鎖定的引擎（`{ upstream_id, fallback_upstream_id }`），或 `null`。</ResponseField>
<ResponseField name="bindings" type="array">按模式的覆蓋設置：`{ mode, upstream_id, fallback_upstream_id }`。</ResponseField>
<ResponseField name="catalog" type="array">可供選擇的引擎列表（平台內置引擎 + 你的自定義提供方），用於構建選擇器。</ResponseField>

## 替換方案

`PUT /api/v1/keys/{id}/model-plan` —— **完整替換**這兩個字段（需要發送完整的目標狀態）。

<ParamField body="single_model" type="object | null">
  `{ upstream_id, fallback_upstream_id? }`，用於為每一次文本輪次鎖定同一個引擎；傳 `null` 則清除該鎖定。
</ParamField>

<ParamField body="bindings" type="object[]">
  按模式的覆蓋設置，每一項為 `{ mode, upstream_id, fallback_upstream_id? }`。所引用的每個上游 id 都會針對平台目錄或你的自定義提供方進行校驗。
</ParamField>

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/model-plan \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "bindings": [
          { "mode": "fast",  "upstream_id": "arca-velox-5.1" },
          { "mode": "think", "upstream_id": "arca-magnus-5.1" }
        ] }'
  ```

  ```ts SDK theme={null}
  await theo.keys.setModelPlan("KEY_ID", {
    single_model: { upstream_id: "anthropic/claude-opus-4.8" }, // 確定性直通
  });
  ```
</CodeGroup>


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