调用工作流

POST /v1/workflow/invoke 从你自己的应用或服务运行工作流部署。

身份验证

在 Authorization 请求头中发送工作区 API 密钥。

Authorization: Bearer YOUR_API_KEY

请求体

打开 Workflows，然后 Deployments，打开你想运行的部署变体,并点击 Code Snippet 即可从 Fetch Hive 复制当前的请求结构。

字段	类型	是否必填	描述
`deployment`	string	是	工作流部署名称
`variant`	string	是	部署变体名称
`inputs`	object	否	在 Start 步骤上定义的变量的键值对
`async`	object	否	回调投递设置
`metadata`	object	否	调用方定义的扁平元数据,用于审计和日志筛选。不会用作工作流输入。

inputs 的值会在运行开始前根据工作流的 Start 输入定义进行校验。数组类型的起始输入必须是原生 JSON 数组,而非 JSON 字符串。 metadata 必须是扁平对象。键必须是非空字符串,值必须是字符串、数字、布尔值或 null。数组和嵌套对象会在运行启动前被拒绝。有效示例：

{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}

无效示例：

{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

如果包含 async,请使用以下嵌套字段：

字段	类型	是否必填	描述
`async.enabled`	boolean	是	设为 `true` 以立即返回
`async.callback_url`	string	启用回调投递时必填	工作流运行完成时 Fetch Hive 应调用的回调 URL

如果在代码片段对话框中开启 Callback delivery，Fetch Hive 还会显示用于回调验证的 Signing secret。

响应

当回调投递关闭时,Fetch Hive 会等待工作流完成,并在一条响应中返回输出。

{
  "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."
}

output 的结构取决于工作流的结果类型。对于图像生成的最终输出,output 是带有 settings 和 assets 的对象：

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": {
    "settings": {
      "model": "grok-imagine-image-quality",
      "provider": "xai",
      "image_count": 1
    },
    "assets": [
      {
        "id": "asset_1",
        "file_url": "https://uploads.fetchhive.com/...png",
        "file_name": "step_3_123456789_1.png",
        "file_size": 505042,
        "file_type": "image/png"
      }
    ]
  }
}

当 async.enabled 为 true 时,Fetch Hive 立即返回。

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

在高并发时,Fetch Hive 也可能返回已入队的回调投递状态。

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

示例

直接请求

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

回调投递请求

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

Fetch Hive API

REST API

Invoke

调用工作流

身份验证

请求体

响应

示例

直接请求

回调投递请求

相关内容

​调用工作流

​身份验证

​请求体

​响应

​示例

​直接请求

​回调投递请求

​相关内容

调用工作流

身份验证

请求体

响应

示例

直接请求

回调投递请求

相关内容