工作流 API

FlowAI工作流API允許您將設計好的工作流程以API形式對外提供服務，便於集成到您的應用或系統中。本指南將幫助您瞭解如何發佈API、管理API密鑰以及如何調用工作流API。

第一部分：發佈與管理API

API發佈流程

要將FlowAI工作流發佈為API，請按照以下步驟操作：

進入您想要發佈的工作流編輯頁面
完成工作流設計並確保功能正常
點擊頂部功能區的發佈API按鈕
點擊保存併發布當前工作流按鈕
在彈出的窗口中確認操作：“此操作將保存當前工作流並將其發佈為最新版本”
發佈成功後，您的工作流即可通過API調用

API密鑰管理

API密鑰是調用FlowAI工作流API的身份憑證，請按照以下步驟管理您的API密鑰：

在左側導航欄中點擊API管理選項
在API管理頁面，您可以：
- 查看現有的API密鑰
- 創建新的API密鑰
- 查看已發佈的工作流列表及其狀態

重要提示：首次使用API功能時，您需要創建API密鑰。點擊”創建新密鑰”按鈕生成新的API密鑰。請妥善保管您的API密鑰，不要在公開場合分享。

第二部分：API調用指南

基本調用格式

FlowAI工作流API採用REST風格，基本調用格式如下：

curl -X POST https://flowai.cc/v1/api/workflow/run/:workflow_ID \
-H 'X-API-KEY: <KEY>' \
-d '{"input":<輸入參數>}'

其中：

:workflow_ID：您的工作流ID（在API管理頁面可以找到）
<KEY>：您的API密鑰
<輸入參數>：根據工作流輸入節點定義的參數對象

參數說明

API請求的主要參數包括：

輸入參數：根據工作流設計，不同的工作流需要不同的輸入參數
- 圖像處理工作流示例：{"input":{"url":"http://example.com/image.jpg"}}
- 文本處理工作流示例：{"input":{"text":"需要處理的文本內容"}}
- 對話工作流示例：{"input":{"輸入":"在嗎？"}}
流式輸出參數：添加"stream":true啟用流式輸出
- 標準調用：{"input":<輸入參數>}
- 流式調用：{"input":<輸入參數>,"stream":true}

返回格式

FlowAI工作流API支持兩種返回模式：標準輸出和流式輸出。

1. 標準輸出

標準輸出模式下，API會在處理完成後一次性返回結果：

請求示例：

curl -X POST https://flowai.cc/v1/api/workflow/run/:workflow_ID \
-H 'X-API-KEY: <KEY>' \
-d '{"input":{"輸入":"在嗎？"}}'

返回示例：

{
  "output": "在呢。",
  "total_time": 9.316849339000001
}

返回字段說明：

output：工作流的最終輸出結果
total_time：工作流執行總耗時（秒）

2. 流式輸出

流式輸出模式適用於包含大型語言模型（LLM）的工作流，能夠實時返回處理過程和結果：

請求示例：

curl -X POST https://flowai.cc/v1/api/workflow/run/:workflow_ID \
-H 'X-API-KEY: <KEY>' \
-d '{"input":{"輸入":"在嗎？"},"stream":true}'

返回示例（Server-Sent Events格式）：

event:msg
data:{"Node":"myinput","Msg":"start","Type":"start","Data":{"輸入":"在嗎？"}}

event:msg
data:{"Node":"myinput","Msg":"Start node 開始, type in","Type":"start_node","Data":null}

event:msg
data:{"Node":"myinput","Msg":"Finish node 開始, type in","Type":"finish_node","Data":{"time_spend":0.000125251}}

event:msg
data:{"Node":"1741675999864","Msg":"Start node LLM1, type llm","Type":"start_node","Data":null}

event:stream
data:{"Content":"嗯","Node":"1741675999864","Reasoning":null}

event:stream
data:{"Content":"，","Node":"1741675999864","Reasoning":null}

event:stream
data:{"Content":"在","Node":"1741675999864","Reasoning":null}

event:stream
data:{"Content":"呢","Node":"1741675999864","Reasoning":null}

event:stream
data:{"Content":"。","Node":"1741675999864","Reasoning":null}

event:msg
data:{"Node":"1741675999864","Msg":"Finish node LLM1, type llm","Type":"finish_node","Data":{"time_spend":4.758483707}}

event:msg
data:{"Node":"1741676038250","Msg":"Start node 結束（輸出）1, type out","Type":"start_node","Data":null}

event:msg
data:{"Node":"1741676038250","Msg":"Finish node 結束（輸出）1, type out","Type":"finish_node","Data":{"time_spend":0.000128861}}

event:output
data:{"output":"嗯，在呢。","total_time":4.758748069}

第三部分：事件類型與示例應用

流式輸出事件類型

流式輸出中包含三種主要事件類型：

event:msg：節點運行日誌
- start：工作流開始運行
- start_node：節點開始執行
- finish_node：節點執行完成，包含耗時
event:stream：LLM流式輸出
- Content：當前生成的文本片段
- Node：生成該內容的節點ID
- Reasoning：推理過程（如適用）
event:output：最終輸出結果
- output：完整輸出內容
- total_time：總耗時
event:error：錯誤的情況會返回

第四部分：最佳實踐與常見問題

API調用實戰建議

異常情況應對

遇到接口報錯別慌，先看狀態碼：
- 401：檢查密鑰是不是複製錯了
- 429：說明觸發限流，該歇會兒再調了
- 5xx：服務器開小差，過幾分鐘再試
網絡波動時建議：
- 給請求加個3次重試（間隔用指數退避）
- 給用戶展示「服務暫時打盹，正在努力喚醒」的友好提示
- 記錄錯誤日誌時記得分類：網絡問題/參數錯誤/服務異常

密鑰安全指南

密鑰保管要像對待銀行卡密碼：

前端項目裡不要寫死密鑰，比如

// 反面教材 ❌
const API_KEY = "sk-123456...";

// 正確姿勢 ✅
const API_KEY = process.env.API_KEY;

推薦用後端做中間人轉發請求
定期更新密鑰

提升響應速度

流式對話場景優化技巧：

使用專業的SSE客戶端庫（比如Python的sseclient）
高頻調用時：
- 設置本地緩存（相同參數請求緩存5分鐘）
- 配置CDN加速靜態資源
- 用漏桶算法控制請求頻率（例如每秒不超過20次）

參數校驗

我們的Workflow不會做內容的校驗，所以在調用前，保證輸入的內容是合法的。

格式驗證：

必填字段用白名單校驗
用正則表達式檢查郵箱/手機號格式

"input": {
  "email": "user@example.com",  // 正則：^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
  "phone": "13800138000"
}

內容過濾：
- 轉義特殊字符（<>&等）
- 敏感詞過濾（政治/廣告/辱罵內容）
邊界處理：
- 文本長度截斷（超過500字提示修改）
- 圖片尺寸限制（建議不超過5MB）

常見問題解答

Q: 如何獲取工作流ID？
A: 在API管理頁面的已發佈工作流列表中可以找到每個工作流的ID，你可以一鍵複製ID和調用的代碼。

Q: 如何處理API調用中的錯誤？
A: API會返回標準HTTP錯誤碼，您應當根據錯誤碼採取相應措施。常見錯誤包括認證失敗(401)、參數錯誤(400)等。

Q: 可以使用其他編程語言調用API嗎？
A: 可以，FlowAI API是基於標準HTTP協議的REST API，可以使用任何支持HTTP請求的編程語言調用。

定製服務

官方團隊為您量身定製專業的自動化解決方案