跳转到主要内容

​
调用工作流

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

​
身份验证

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

​
请求体

打开 Workflows，然后 Deployments，打开你想运行的部署变体,并点击 Code Snippet 即可从 Fetch Hive 复制当前的请求结构。
字段类型是否必填描述
deploymentstring是工作流部署名称
variantstring是部署变体名称
inputsobject否在 Start 步骤上定义的变量的键值对
asyncobject否回调投递设置
metadataobject否调用方定义的扁平元数据,用于审计和日志筛选。不会用作工作流输入。
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.enabledboolean是设为 true 以立即返回
async.callback_urlstring启用回调投递时必填工作流运行完成时 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

​
相关内容