跳转到主要内容

​
使用 API 运行

当你想从自己的应用或服务运行工作流部署时，请使用公共工作流调用端点。先在仪表板中创建工作流部署，选择一个变体，然后在请求中使用部署的详细信息。 如果外部产品需要通过直接向 Fetch Hive 发送 Webhook 来启动工作流，请改用部署助手中的 Webhook 触发 URL。该流程使用 X-Fetch-Hive-Webhook-Secret 而不是工作区 API 密钥。请参阅 回调投递与 Webhook 触发。

​
身份验证

Authorization: Bearer YOUR_API_KEY
有关如何创建和管理密钥，请参阅 API 密钥。

​
端点

POST https://api.fetchhive.com/v1/workflow/invoke 在调用此端点之前，请先从工作流编辑器创建工作流部署和变体。请参阅 发布与版本管理 了解该 UI 流程。

​
请求

使用以下请求结构：
字段类型必填描述
deploymentstring是工作流部署键
variantstring是你想运行的部署变体
inputsobject否工作流 Start 步骤定义的变量的键值对
asyncobject否回调投递设置。请参阅 回调投递与 Webhook 触发
metadataobject否调用方定义的扁平元数据，用于审计和日志过滤。不会作为工作流输入使用。
inputs 的值必须与工作流 Start 输入类型匹配。文本输入接受字符串。数组输入必须是原生 JSON 数组，例如 "companies": [{"name":"Fetch Hive"}]。数组在工作流变量和日志中作为数组保留。 metadata 必须是扁平的且仅包含标量：字符串、数字、布尔值或 null。嵌套对象和数组会在运行启动之前返回验证错误。 如果你包含 async，请使用这些嵌套字段：
字段类型必填描述
async.enabledboolean是设置为 true 以立即返回，并通过签名回调稍后投递结果
async.callback_urlstring启用回调投递时必填运行完成时 Fetch Hive 应调用的回调 URL
包含 Human in the Loop 步骤的工作流必须使用回调投递。请将 async.enabled 设置为 true 并提供 async.callback_url；同步调用会返回验证错误，因为运行会暂停直到所配置的工作区成员提交选择。

​
基本示例

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 中。请参阅 调用元数据 获取示例和日志过滤详情。

​
回调投递示例

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 触发。

​
响应

​
直接响应

当你未启用回调投递时，公共路由会等待工作流完成并返回最终输出。例如： 
{
  "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 时，路由会立即返回。例如： 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
在高并发情况下，路由也可以返回排队状态的回调投递： 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

​
错误

当请求无效或运行失败时，路由会返回错误对象。例如： 
{
  "error": "Missing required field: deployment or variant"
}
有关工作流特有的失败案例，请参阅 错误处理；有关回调验证错误，请参阅 回调投递与 Webhook 触发。

​
后续步骤