> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 API 运行

> 使用你的 API 密钥、部署名称、变体和启动输入，通过公共 API 调用工作流部署

# 使用 API 运行

当你想从自己的应用或服务运行工作流部署时，请使用公共工作流调用端点。先在仪表板中创建工作流部署，选择一个变体，然后在请求中使用部署的详细信息。

如果外部产品需要通过直接向 Fetch Hive 发送 Webhook 来启动工作流，请改用部署助手中的 Webhook 触发 URL。该流程使用 `X-Fetch-Hive-Webhook-Secret` 而不是工作区 API 密钥。请参阅 [回调投递与 Webhook 触发](./async-and-webhooks)。

## 身份验证

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

有关如何创建和管理密钥，请参阅 [API 密钥](../workspace/api-keys)。

## 端点

`POST https://api.fetchhive.com/v1/workflow/invoke`

在调用此端点之前，请先从工作流编辑器创建工作流部署和变体。请参阅 [发布与版本管理](./publishing-and-versioning) 了解该 UI 流程。

## 请求

使用以下请求结构：

| 字段           | 类型     | 必填 | 描述                                                  |
| ------------ | ------ | -- | --------------------------------------------------- |
| `deployment` | string | 是  | 工作流部署键                                              |
| `variant`    | string | 是  | 你想运行的部署变体                                           |
| `inputs`     | object | 否  | 工作流 **Start** 步骤定义的变量的键值对                           |
| `async`      | object | 否  | 回调投递设置。请参阅 [回调投递与 Webhook 触发](./async-and-webhooks) |
| `metadata`   | object | 否  | 调用方定义的扁平元数据，用于审计和日志过滤。不会作为工作流输入使用。                  |

`inputs` 的值必须与工作流 **Start** 输入类型匹配。文本输入接受字符串。数组输入必须是原生 JSON 数组，例如 `"companies": [{"name":"Fetch Hive"}]`。数组在工作流变量和日志中作为数组保留。

`metadata` 必须是扁平的且仅包含标量：字符串、数字、布尔值或 `null`。嵌套对象和数组会在运行启动之前返回验证错误。

如果你包含 `async`，请使用这些嵌套字段：

| 字段                   | 类型      | 必填        | 描述                             |
| -------------------- | ------- | --------- | ------------------------------ |
| `async.enabled`      | boolean | 是         | 设置为 `true` 以立即返回，并通过签名回调稍后投递结果 |
| `async.callback_url` | string  | 启用回调投递时必填 | 运行完成时 Fetch Hive 应调用的回调 URL    |

包含 Human in the Loop 步骤的工作流必须使用回调投递。请将 `async.enabled` 设置为 `true` 并提供 `async.callback_url`；同步调用会返回验证错误，因为运行会暂停直到所配置的工作区成员提交选择。

## 基本示例

```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    }
  }' \
  --compressed
```

这与工作流部署 UI 中显示的 cURL 代码段匹配。部署 UI 目前显示 cURL 示例，**Python** 和 **TypeScript** 选项卡仍显示 **Coming Soon**。

将 `metadata` 用于你希望在日志中查看或过滤的审计字段，例如客户 ID、套餐名称、地区或实验名称。工作流的启动变量应放在 `inputs` 中。请参阅 [调用元数据](../user-tracking/invoke-metadata) 获取示例和日志过滤详情。

## 回调投递示例

```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/callback"
    },
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    }
  }' \
  --compressed
```

有关即时响应和签名回调投递如何工作的更多信息，请参阅 [回调投递与 Webhook 触发](./async-and-webhooks)。

## 响应

### 直接响应

当你未启用回调投递时，公共路由会等待工作流完成并返回最终输出。例如：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}
```

### 回调投递响应

当 `async.enabled` 为 `true` 时，路由会立即返回。例如：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

在高并发情况下，路由也可以返回排队状态的回调投递：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

## 错误

当请求无效或运行失败时，路由会返回错误对象。例如：

```json theme={null}
{
  "error": "Missing required field: deployment or variant"
}
```

有关工作流特有的失败案例，请参阅 [错误处理](./error-handling)；有关回调验证错误，请参阅 [回调投递与 Webhook 触发](./async-and-webhooks)。

## 后续步骤

* [回调投递与 Webhook 触发](./async-and-webhooks)
* [错误处理](./error-handling)
* [使用 Python SDK 运行](./run-with-python-sdk)
* [使用 Node.js SDK 运行](./run-with-nodejs-sdk)
* [使用 Ruby SDK 运行](./run-with-ruby-sdk)
* [使用 PHP SDK 运行](./run-with-php-sdk)