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