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

# 密鑰

> 通過代碼創建和配置 API 密鑰 —— 模型方案、編排器圖、技能、路由和護欄 —— 使用 theo.keys.*。

`theo.keys` 命名空間用於創建 API 密鑰，並以編程方式塑造其 **按密鑰編排**：模型方案、編排器圖、技能允許列表、路由偏好以及護欄策略。它是儀表盤編排器界面以及 [MCP 配置工具](/mcp/tools) 背後所使用的 SDK 接口。

<Note>
  此處的每個方法都要求調用密鑰持有 **`billing`** 權限範圍（密鑰創建和按密鑰配置屬於賬戶管理操作）。你所配置的內容會同時應用於該密鑰在原生 `/v1/completions` 端點和兼容 OpenAI 的 `/v1/chat/completions` 端點上的行為。
</Note>

下文使用的引擎 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>`。

## `keys.create`

創建一個新的 API 密鑰。原始密鑰僅會返回 **一次** —— 請立即保存。

```ts theme={null}
const created = await theo.keys.create({
  name: "coding backend",
  scopes: ["completions", "skills", "tools"], // optional; defaults applied server-side
  scope: "personal",                           // or "org" (+ org_id) for a team key
});
console.log(created.key);   // theo_sk_… (shown once)
console.log(created.id);    // the key UUID — use it for the calls below
```

| 字段 | 類型 | 說明 |
| - | - | - |
| `name` | `string` | 可選標籤。 |
| `scopes` | `("completions" \| "skills" \| "tools" \| "connectors" \| "billing")[]` | 可選的權限範圍集合。 |
| `scope` | `"personal" \| "org"` | `org` 用於創建團隊密鑰（需要 `org_id`）。 |
| `org_id` | `string` | 團隊密鑰所屬的目標組織。 |

返回 `CreatedApiKey`（`{ id, key, name, scopes, … }`）。

## `keys.getModelPlan` / `keys.setModelPlan`

模型方案是控制密鑰運行所用引擎的最簡單方式。`single_model` 會為每一輪文本對話固定 **單一** 引擎 —— 這是一種確定性的直通模式，會跳過分類器（非常適合編碼 / IDE 後端場景，也包括 `custom:` [自帶模型（BYO model）](#bring-your-own-models)）。而 `bindings` 則是按模式分別重映射。

```ts theme={null}
// Pin one engine for everything (deterministic passthrough):
await theo.keys.setModelPlan(created.id, {
  single_model: { upstream_id: "anthropic/claude-opus-4.8" },
});

// Or remap per mode (classifier still routes; each mode's engine is pinned):
await theo.keys.setModelPlan(created.id, {
  bindings: [
    { mode: "fast",  upstream_id: "arca-velox-5.1" },
    { mode: "think", upstream_id: "arca-magnus-5.1" },
  ],
});

// Clear the single-model pin:
await theo.keys.setModelPlan(created.id, { single_model: null });

const plan = await theo.keys.getModelPlan(created.id); // KeyModelPlan
```

每個綁定都可以選填一個 `fallback_upstream_id`，在主引擎不可用時會用它進行回退。

## `keys.getOrchestratorGraph` / `keys.setOrchestratorGraph`

如需完全掌控，可以設置一個可運行的編排器圖 —— `入口 → 分類器 / 路由器 → 模型 → 護欄`。一個 **啓用** 狀態的圖必須包含一個入口節點，以及至少一個帶有引擎的模型節點。

```ts theme={null}
await theo.keys.setOrchestratorGraph(created.id, {
  enabled: true,
  nodes: [
    { id: "entry", type: "entry", position: { x: 0, y: 0 }, config: { label: "User Prompt" } },
    { id: "classifier", type: "classifier", position: { x: 300, y: 0 }, config: { label: "Classifier" } },
    { id: "m_fast", type: "model", position: { x: 640, y: -80 }, config: { upstreamId: "arca-velox-5.1", label: "fast" } },
    { id: "m_think", type: "model", position: { x: 640, y: 80 }, config: { upstreamId: "arca-magnus-5.1", label: "think" } },
  ],
  edges: [
    { id: "e_in", source: "entry", target: "classifier" },
    { id: "e_fast", source: "classifier", target: "m_fast", modes: ["fast"] },
    { id: "e_think", source: "classifier", target: "m_think", modes: ["think"] },
  ],
});

const { graph } = await theo.keys.getOrchestratorGraph(created.id); // graph is null when none is set
```

放在模型節點之前的護欄節點（`type: "guardrail"`，`config.guardrailPolicyId`）會對提示詞（輸入）進行審查；放在模型節點之後，則會對回覆（輸出）進行審查。路由器節點會應用該密鑰所綁定的[路由偏好](#routing--guardrails)。

## `keys.getSkills` / `keys.setSkills`

設置該密鑰的技能允許列表。每個綁定授予一項技能；可選的 `mode` 字段可將其限定到單一模式（省略 / `null` 表示適用於所有模式）。

```ts theme={null}
await theo.keys.setSkills(created.id, [
  { skill_id: "sk_deep_research", mode: "think" },
  { skill_id: "sk_content_writer" },
]);

const { bindings } = await theo.keys.getSkills(created.id);
```

空的允許列表意味着 **繼承全部**（該密鑰可以調用所有者已安裝的任意技能）。

## 路由與護欄

`keys` 上還有另外兩個綁定方法，其文檔與各自的功能頁面放在一起：

* **`keys.getRoutingPreference` / `keys.setRoutingPreference`** —— 綁定路由工作室（Routing Studio）中的偏好設置（關鍵詞/正則 → 模式）。參見[路由工作室](/sdk-reference/routing-studio)。
* **`keys.getGuardrailPolicy` / `keys.setGuardrailPolicy`** —— 綁定網關護欄（Gateway Guardrails）策略。參見[護欄](/sdk-reference/guardrails)。

## 自帶模型

註冊你自己的兼容 OpenAI 的端點，然後在 `setModelPlan`（`single_model`）中，或在圖的模型節點上，通過其 `custom:<providerId>:<model>` id 引用它。你可以為每個模型聲明其 **上下文窗口**，這樣超大的請求就能在到達你的端點之前被攔截。參見[更新日誌](/changelog)以及[自定義提供方 REST 端點](/api-reference/overview)。發送給你自己模型的提示詞是免費的，不會消耗額度。

## 計費輔助方法

從代碼中充值額度或打開計費門戶（這些方法位於頂層，不在 `keys` 之下）：

```ts theme={null}
const { checkout_url } = await theo.billingCheckout({ amount_cents: 2000, scope: "personal" });
const { portal_url } = await theo.billingPortal();
```

`scope: "org"` 用於為團隊額度池充值 / 進行管理。


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