> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作流

> 以你的輸入執行 Blon 工作流。

工作流是在 Blon 畫布上組成的步驟圖。每次執行都針對工作流的某一個確切**版本（revision）**，以其 id 指定，輸入與輸出固定。

工作流相關回應的欄位使用 `camelCase`。

## 讀取介面

```bash theme={null}
curl https://api.blon.ai/v1/workflows/$REVISION_ID \
  -H "Authorization: Bearer $BLON_API_KEY"
```

回應描述該版本：

| 欄位 | 說明 |
| - | - |
| `id`、`version` | 版本 id 與版本號 |
| `inputs` | 每項含 `id`、`description`、`required`、`schema`、`cardinality` 與選填的 `default` |
| `outputs` | 每項含 `id`、`label`、`schema` 與 `cardinality` |

輸入的 `schema.kind` 與模型輸入同一套值型別：`text`、`number`、`boolean`、`media`、`list` 或 `voice`。媒體值為 `{ "asset_id": "…" }` 或 `{ "url": "https://…" }`。

## 啟動執行

必須帶 `Idempotency-Key`，否則回 `400 bad_request`。

```bash theme={null}
curl https://api.blon.ai/v1/workflows/$REVISION_ID/runs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inputs":{"prompt":"A ceramic teapot on a linen table"}}'
```

`202` 回應包含 `runId`、`status` 與 `statusUrl`。同一把鍵回同一次執行；同一把鍵但輸入不同回 `409 idempotency_conflict`。

## 讀取執行

```bash theme={null}
curl https://api.blon.ai/v1/workflow-runs/$RUN_ID \
  -H "Authorization: Bearer $BLON_API_KEY"
```

| 欄位 | 說明 |
| - | - |
| `status` | `PLANNED`、`RUNNING`、`SUCCEEDED`、`PARTIAL`、`FAILED` 或 `CANCELLED` |
| `nodes` | 每個步驟的 `nodeId`、`status` 與 `progress` |
| `errors` | 每個失敗步驟的 `nodeId` 與 `message` |
| `creditSummary` | `quotedCredits` 與 `chargedCredits` |
| `outputs`、`missing` | 執行產出後的宣告輸出，以及未產出的項目 |
| `createdAt`、`startedAt`、`completedAt` | 時間 |

`SUCCEEDED`、`PARTIAL`、`FAILED` 與 `CANCELLED` 是終態。

## 使用 CLI

```bash theme={null}
blon workflows get $REVISION_ID
blon workflows run $REVISION_ID --prompt "A ceramic teapot" --wait
```

工作流的每個輸入就是一個 `--<inputId>` 旗標；media、list 與 voice 的值以 JSON 傳入。

## 錯誤

| 錯誤 | 情況 |
| - | - |
| `404 not_found` | 找不到版本或執行，或你沒有讀取權限 |
| `400 invalid_input` | body 不是 `{ "inputs": { … } }` |
| `402 insufficient_credits` | 餘額不足以執行 |
| `412 precondition_failed` | 此版本目前無法執行 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.