Skip to main content
theo.keys 命名空間用於創建 API 密鑰,並以編程方式塑造其 按密鑰編排:模型方案、編排器圖、技能允許列表、路由偏好以及護欄策略。它是儀表盤編排器界面以及 MCP 配置工具 背後所使用的 SDK 接口。
此處的每個方法都要求調用密鑰持有 billing 權限範圍(密鑰創建和按密鑰配置屬於賬戶管理操作)。你所配置的內容會同時應用於該密鑰在原生 /v1/completions 端點和兼容 OpenAI 的 /v1/chat/completions 端點上的行為。
下文使用的引擎 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 密鑰。原始密鑰僅會返回 一次 —— 請立即保存。
返回 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" 用於為團隊額度池充值 / 進行管理。