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

# 密钥编排器图

> 读取或替换某个密钥的可执行编排器图——入口 → 分类器/路由器 → 模型 → 护栏。

编排器图是一个按密钥运行的可执行流程：`Entry → Classifier / Router → Model → Guardrail`（入口 → 分类器 / 路由器 → 模型 → 护栏）。当 `enabled` 为真时，发往该密钥的每一次请求都会沿着你绘制的路径运行——路由、模型选择、各节点技能以及护栏都会一并生效。它的优先级高于[模型方案](/api-reference/keys/model-plan)，并且在原生端点和兼容 OpenAI 的端点上**同时**生效。

这是仪表盘中编排器画布以及 [MCP 配置工具](/mcp/tools)背后的 REST 接口。

## 身份验证

需要拥有 `billing` 权限范围的 API 密钥；调用方必须是该密钥的所有者。

## 路径参数

<ParamField path="id" type="string" required>API 密钥的 UUID。</ParamField>

## 获取图

`GET /api/v1/keys/{id}/orchestrator-graph`

<ResponseField name="key_id" type="string">API 密钥的 UUID。</ResponseField>
<ResponseField name="graph" type="object | null">已保存的图（`{ version, enabled, nodes, edges }`），若未设置则为 `null`。</ResponseField>

## 替换图

`PUT /api/v1/keys/{id}/orchestrator-graph`

<ParamField body="enabled" type="boolean" required>
  为 `true` 时，编排器将运行该图。启用的图**必须**包含一个 `entry` 节点，以及至少一个带有引擎的 `model` 节点，否则请求会被拒绝。
</ParamField>

<ParamField body="nodes" type="object[]" required>
  最多 100 个节点。每个节点的结构为：`{ id, type, position?, config? }`。`type` 取值为 `entry`、`classifier`、`router`、`model`、`guardrail`、`description`、`output` 之一。模型节点的 `config.upstreamId` 即其引擎；护栏节点的 `config.guardrailPolicyId` 即其策略（位于模型之前 = 审查输入，之后 = 审查输出）。
</ParamField>

<ParamField body="edges" type="object[]" required>
  每条边的结构为：`{ id, source, target, modes?, when?, default? }`。分类器分支使用 `modes`（该边所对应的模式）；路由器分支使用 `when`（关键词）；`default` 为回退边。
</ParamField>

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/orchestrator-graph \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "nodes": [
        { "id": "entry", "type": "entry", "config": { "label": "User Prompt" } },
        { "id": "classifier", "type": "classifier", "config": { "label": "Classifier" } },
        { "id": "m_fast", "type": "model", "config": { "upstreamId": "arca-velox-5.1", "label": "fast" } },
        { "id": "m_think", "type": "model", "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"] }
      ]
    }'
  ```

  ```ts SDK theme={null}
  await theo.keys.setOrchestratorGraph("KEY_ID", { enabled: true, nodes, edges });
  ```
</CodeGroup>


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