theo.keys 命名空间用于创建 API 密钥,并以编程方式塑造其 按密钥编排:模型方案、编排器图、技能允许列表、路由偏好以及护栏策略。它是仪表盘编排器界面以及 MCP 配置工具 背后所使用的 SDK 接口。
此处的每个方法都要求调用密钥持有
billing 权限范围(密钥创建和按密钥配置属于账户管理操作)。你所配置的内容会同时应用于该密钥在原生 /v1/completions 端点和兼容 OpenAI 的 /v1/chat/completions 端点上的行为。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 密钥。原始密钥仅会返回 一次 —— 请立即保存。
返回
CreatedApiKey({ id, key, name, scopes, … })。
keys.getModelPlan / keys.setModelPlan
模型方案是控制密钥运行所用引擎的最简单方式。single_model 会为每一轮文本对话固定 单一 引擎 —— 这是一种确定性的直通模式,会跳过分类器(非常适合编码 / IDE 后端场景,也包括 custom: 自带模型(BYO model))。而 bindings 则是按模式分别重映射。
fallback_upstream_id,在主引擎不可用时会用它进行回退。
keys.getOrchestratorGraph / keys.setOrchestratorGraph
如需完全掌控,可以设置一个可运行的编排器图 —— 入口 → 分类器 / 路由器 → 模型 → 护栏。一个 启用 状态的图必须包含一个入口节点,以及至少一个带有引擎的模型节点。
type: "guardrail",config.guardrailPolicyId)会对提示词(输入)进行审查;放在模型节点之后,则会对回复(输出)进行审查。路由器节点会应用该密钥所绑定的路由偏好。
keys.getSkills / keys.setSkills
设置该密钥的技能允许列表。每个绑定授予一项技能;可选的 mode 字段可将其限定到单一模式(省略 / null 表示适用于所有模式)。
路由与护栏
keys 上还有另外两个绑定方法,其文档与各自的功能页面放在一起:
keys.getRoutingPreference/keys.setRoutingPreference—— 绑定路由工作室(Routing Studio)中的偏好设置(关键词/正则 → 模式)。参见路由工作室。keys.getGuardrailPolicy/keys.setGuardrailPolicy—— 绑定网关护栏(Gateway Guardrails)策略。参见护栏。
自带模型
注册你自己的兼容 OpenAI 的端点,然后在setModelPlan(single_model)中,或在图的模型节点上,通过其 custom:<providerId>:<model> id 引用它。你可以为每个模型声明其 上下文窗口,这样超大的请求就能在到达你的端点之前被拦截。参见更新日志以及自定义提供方 REST 端点。发送给你自己模型的提示词是免费的,不会消耗额度。
计费辅助方法
从代码中充值额度或打开计费门户(这些方法位于顶层,不在keys 之下):
scope: "org" 用于为团队额度池充值 / 进行管理。