---
title: API 触发器
description: 通过经过身份验证的 HTTP 请求启动工作流
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Image } from '@/components/ui/image'

## 概述

API 触发器将您的工作流公开为一个安全的 HTTP 端点。将 JSON 数据发送到该端点，您的工作流会立即处理它。API 调用始终针对您的最新部署执行。

## 配置输入格式

<div className='flex justify-center my-6'>
  <Image
    src='/static/triggers/api-trigger-light.png'
    alt='API 触发器输入格式'
    width={400}
    height={250}
    className='rounded-xl border border-border shadow-sm'
  />
</div>

为每个参数添加一个 **输入格式** 字段。运行时输出键会镜像该模式，并且也可以在 `<api.input>` 下使用。

在编辑器中手动运行使用 `value` 列，因此您可以在不发送请求的情况下进行测试。在执行过程中，解析器会填充 `<api.userId>` 和 `<api.input.userId>`。

## 请求示例

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{"userId":"demo-user","maxTokens":1024}'
```

成功的响应会返回来自执行器的序列化执行结果。错误会显示验证、认证或工作流失败的信息。

## 流式响应

启用实时流式传输以在生成时逐字符接收工作流输出。这对于向用户逐步显示 AI 响应非常有用。

### 请求参数

添加以下参数以启用流式传输：

- `stream` - 设置为 `true` 以启用服务器发送事件 (SSE) 流式传输
- `selectedOutputs` - 要流式传输的块输出数组（例如，`["agent1.content"]`）

### 块输出格式

使用 `blockName.attribute` 格式指定要流式传输的块输出：
- 格式：`"blockName.attribute"`（例如，如果您想流式传输 Agent 1 块的内容，可以使用 `"agent1.content"`）
- 块名称不区分大小写，空格会被忽略

### 示例请求

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Count to five",
    "stream": true,
    "selectedOutputs": ["agent1.content"]
  }'
```

### 响应格式

流式响应使用服务器发送事件 (SSE) 格式：

```
data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", three"}

data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}

data: [DONE]
```

每个事件包括：
- **流式块**：`{"blockId": "...", "chunk": "text"}` - 实时生成的文本
- **最终事件**：`{"event": "done", ...}` - 执行元数据和完整结果
- **终止符**：`[DONE]` - 表示流结束

### 多块流式传输

当 `selectedOutputs` 包含多个块时，每个块会指示其来源：

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Process this request",
    "stream": true,
    "selectedOutputs": ["agent1.content", "agent2.content"]
  }'
```

每个块中的 `blockId` 字段可让您将输出路由到正确的 UI 元素：

```
data: {"blockId":"agent1-uuid","chunk":"Processing..."}

data: {"blockId":"agent2-uuid","chunk":"Analyzing..."}

data: {"blockId":"agent1-uuid","chunk":" complete"}
```

## 输出参考

| 参考 | 描述 |
|-----------|-------------|
| `<api.field>` | 输入格式中定义的字段 |
| `<api.input>` | 整个结构化请求体 |

如果未定义输入格式，执行器仅在 `<api.input>` 处暴露原始 JSON。

<Callout type="warning">
一个工作流只能包含一个 API 触发器。更改后发布新部署，以确保端点保持最新。
</Callout>

### 文件上传格式

API 接受两种格式的文件：

**1. Base64 编码文件**（推荐用于 SDK）：

```json
{
  "documents": [{
    "type": "file",
    "data": "data:application/pdf;base64,JVBERi0xLjQK...",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}
```

- 单个文件的最大大小：20MB
- 文件会上传到云存储，并转换为具有所有属性的 UserFile 对象

**2. 直接 URL 引用**：

```json
{
  "documents": [{
    "type": "url",
    "data": "https://example.com/document.pdf",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}
```

- 文件不会上传，URL 会直接传递
- 适用于引用现有文件

### 文件属性

对于文件，可以访问所有属性：

| 属性 | 描述 | 类型 |
|----------|-------------|------|
| `<api.fieldName[0].url>` | 签名下载 URL | string |
| `<api.fieldName[0].name>` | 原始文件名 | string |
| `<api.fieldName[0].size>` | 文件大小（字节） | number |
| `<api.fieldName[0].type>` | MIME 类型 | string |
| `<api.fieldName[0].uploadedAt>` | 上传时间戳（ISO 8601） | string |
| `<api.fieldName[0].expiresAt>` | URL 过期时间戳（ISO 8601） | string |

对于 URL 引用的文件，除了 `uploadedAt` 和 `expiresAt` 外，其他属性均可用，因为文件未上传到我们的存储中。

如果未定义输入格式，执行器将仅在 `<api.input>` 处暴露原始 JSON。

<Callout type="warning">
一个工作流只能包含一个 API 触发器。更改后发布新的部署，以确保端点保持最新。
</Callout>
