第 9 章

探索 API 的活用

在 Dify 裡做好的每一個應用，都自動是一個 REST API。這一章我們離開瀏覽器，改用 cURL 與程式碼呼叫前幾章的成果——把 Dify 當成你系統的「AI 後端」（BaaS）。以下所有指令與回應都是本機實測的真實結果。

本章目標

要學什麼: 探索 Dify 作為 API 的活用方式
學會的技能: 取得 API 金鑰、Chat API／Workflow API 呼叫、Streaming 串流接收、與自有系統整合的思路
能做出什麼: 前面所有應用的 API 化、嵌入公司系統的 AI 功能

9.1取得 API 金鑰

打開任何應用，左側選單的「訪問 API」就是這個應用專屬的 API 文件。右上角「API 金鑰」→「建立金鑰」，會得到一把 app- 開頭的金鑰：

應用的訪問 API 頁面，顯示完整 API 文件 — **圖 9-1**「訪問 API」頁面：左邊是端點清單，右邊是請求／回應範例——每個應用都自帶一份量身打造的 API 文件。

API 金鑰管理視窗 — **圖 9-2**API 金鑰管理。**每個應用的金鑰各自獨立**——聊天機器人的金鑰不能呼叫工作流，權限天然隔離。

注意
金鑰等於應用的使用權，放後端環境變數，永遠不要寫進前端程式碼或公開的儲存庫。

9.2Chat API：呼叫聊天機器人

對第 2 章的「我的第一個聊天機器人」發出一個問題（blocking 模式＝等完整回答一次回傳）：

curl -X POST http://localhost/v1/chat-messages \
  -H "Authorization: Bearer app-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "推薦一個台中的景點，一句話就好",
    "response_mode": "blocking",
    "user": "api-demo"
  }'

實際回應（節錄）：

{
  "event": "message",
  "conversation_id": "ce8a004d-5233-4d45-a2c6-d99bb2a331d7",
  "answer": "台中的宮原眼科很值得一去，融合日式古蹟建築與精緻甜點冰淇淋，
             拍照吃美食都超享受的！🍨✨",
  "metadata": {
    "usage": { "total_tokens": 142, "total_price": "0.001134", "latency": 2.79 }
  }
}

query：使用者的話；inputs：應用有設變數時從這裡傳。
conversation_id：多輪對話的關鍵——下一次請求帶上它，機器人就記得前文。
user：終端使用者識別字串，日誌與統計依它區分使用者。
metadata.usage：Token 消耗與成本，方便自行記帳。

9.3Workflow API：呼叫工作流

第 6 章的「天氣速報」也能用 API 跑，端點換成 /v1/workflows/run，輸入放進 inputs：

curl -X POST http://localhost/v1/workflows/run \
  -H "Authorization: Bearer app-工作流的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "city": "Kaohsiung" },
    "response_mode": "blocking",
    "user": "api-demo"
  }'

實際回應的重點欄位：

"outputs": { "weather": "Kaohsiung: 🌤️  +33°C" },
"status": "succeeded"

outputs 的鍵正是輸出節點裡定義的變數名 weather——你在畫布上設計的介面，就是 API 的介面。

9.4Streaming：像 ChatGPT 一樣逐字輸出

把 response_mode 改成 streaming，回應變成 SSE（Server-Sent Events）串流，一小段一小段送達：

data: {"event":"message","answer":"**府城古早味**", ...}
data: {"event":"message","answer":" 😊\n\n台南是台灣歷史最悠久的城市，保留濃厚古", ...}
data: {"event":"message","answer":"蹟氛圍與道地小吃，像", ...}
data: {"event":"message","answer":"度小月擔仔麵、棺", ...}
...
data: {"event":"message_end", "metadata": {...}}

前端把每個 event: message 的 answer 逐段接到畫面上，就是打字機效果；收到 message_end 表示結束。Python 端用 requests 的 stream=True 逐行讀取即可，搭配 Gradio 幾十行就能做出自己的聊天介面。

9.5整合藍圖：Dify 作為 BaaS

你的系統	呼叫的 Dify 應用	端點
官網客服視窗	Chatflow（第 8 章）	`/v1/chat-messages`
後台批次任務	Workflow（第 5、6 章）	`/v1/workflows/run`
行動 App 的 AI 功能	Agent（第 4 章）	`/v1/chat-messages`（回應含工具事件）
內容管理系統	Knowledge API 自動同步文件到知識庫	`/v1/datasets/...`

重點
Knowledge API 值得特別記住：可以用程式建立資料集、新增／更新文件——讓公司的文件系統每晚自動同步到 Dify 知識庫，RAG 的資料就永遠是新的。端點文件在「知識庫」頁面右上角的「服務 API」。

9.6本章回顧

每個應用自帶 API 與文件；金鑰按應用隔離，從「訪問 API」頁建立。
聊天用 /v1/chat-messages（記得傳回 conversation_id 延續對話）；工作流用 /v1/workflows/run。
blocking 適合後端任務，streaming（SSE）適合面向使用者的即時介面。
Knowledge API 讓知識庫可被程式維護，Dify 徹底成為你的 AI 後端。

最後一章，我們深入引擎室：Docker 部署的內部構造、環境變數客製化，以及用 Ollama 讓一切——包括模型——都在你自己的電腦上運行。