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