---
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` - Server-Sent Events (SSE)ストリーミングを有効にするには `true` に設定します
- `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"]
  }'
```

### レスポンスフォーマット

ストリーミングレスポンスはServer-Sent Events (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">
ワークフローには1つのAPIトリガーのみ含めることができます。変更後は新しいデプロイメントを公開して、エンドポイントを最新の状態に保ってください。
</Callout>

### ファイルアップロードフォーマット

APIは2つのフォーマットでファイルを受け付けます：

**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">
ワークフローには1つのAPIトリガーしか含めることができません。変更後は新しいデプロイメントを公開して、エンドポイントを最新の状態に保ってください。
</Callout>
