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

# Invoke

> 使用部署名称、变体和起始输入,通过公开的 Fetch Hive API 运行工作流部署

# 调用工作流

`POST /v1/workflow/invoke`

从你自己的应用或服务运行工作流部署。

## 身份验证

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

```bash theme={null}
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`。数组和嵌套对象会在运行启动前被拒绝。

有效示例：

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

无效示例：

```json theme={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**。

{/* Add screenshot: Signing secret section in the workflow code snippet modal */}

## 响应

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

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

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

```json theme={null}
{
  "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 立即返回。

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

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

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

## 示例

### 直接请求

```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
```

### 回调投递请求

```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
```

## 相关内容

* 请参阅[身份验证](./authentication)了解 API 密钥设置
* 请参阅[回调投递和 Webhook 触发器](../workflows/async-and-webhooks)了解回调投递和签名验证
* 请参阅[通过 API 运行](../workflows/run-with-api)获取面向工作流的指南