本文檔提供了有關 Dify 中與文本生成相關的 API 端點的全面信息。文本生成 API 支持無會話持久性的單次請求文本生成，使其適用于翻譯、摘要、文章寫作等非對話式人工智能應用場景。
概述
文本生成 API 端點允許開發人員將 Dify 的文本生成功能集成到不需要維護對話上下文的應用程序中。每個請求都獨立處理，僅根據該請求中提供的輸入生成內容。
身份驗證
所有 API 端點都需要使用 API 密鑰進行身份驗證。API 密鑰應使用承載令牌格式包含在 Authorization HTTP 標頭中。
Authorization: Bearer {API_KEY}
重要提示：出于安全原因，請始終將 API 密鑰存儲在服務器端，切勿存儲在客戶端代碼或應用程序中。API 密鑰泄露可能導致未經授權的訪問和潛在的經濟損失。
主要端點：創建文本生成消息
端點詳情
- URL：
/completion-messages - 方法：POST
- 目的：根據提供的輸入生成文本內容
請求格式
| 參數 | 類型 | 必填 | 描述 |
|---|---|---|---|
| inputs | object | 是 | 包含至少一個 query 字段的輸入參數 |
| response_mode | string | 否 | “streaming”（推薦）或 “blocking” |
| user | string | 是 | 用于跟蹤和統計的唯一用戶標識符 |
| files | array | 否 | 請求中包含的文件列表（支持圖像） |
示例請求體
{"inputs": {"query": "Summarize the benefits of artificial intelligence in healthcare"},"response_mode": "streaming","user": "user-123"
}
對于包含文件的請求，files 數組可以包含描述每個文件的對象：
{"files": [{"type": "image","transfer_method": "remote_url","url": "https://example.com/image.jpg"}]
}
響應格式
- 阻塞模式：在阻塞模式下，API 在處理完成后返回完整響應：
{"event": "message","message_id": "9da23599-e713-473b-982c-4328d4f5c78a","mode": "completion","answer": "The benefits of artificial intelligence in healthcare include...","metadata": {"usage": {"prompt_tokens": 1033,"prompt_unit_price": "0.001","prompt_price_unit": "0.001","prompt_price": "0.0010330","completion_tokens": 128,"completion_unit_price": "0.002","completion_price_unit": "0.001","completion_price": "0.0002560","total_tokens": 1161,"total_price": "0.0012890","currency": "USD","latency": 0.7682376249867957}},"created_at": 1705407629
}
- 流式模式：在流式模式下，API 使用服務器發送事件（SSE）在生成響應時返回響應塊：
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "metadata": {"usage": {...}}}
每個流式塊都有特定的事件類型和相應的結構：
| 事件類型 | 描述 | 關鍵字段 |
|---|---|---|
| message | 來自大語言模型的文本塊 | message_id, answer, created_at |
| message_end | 流式傳輸結束 | message_id, metadata |
| tts_message | 文本轉語音音頻 | message_id, audio（base64 編碼） |
| tts_message_end | 文本轉語音流結束 | message_id |
| message_replace | 內容替換 | message_id, answer |
| error | 錯誤信息 | status, code, message |
| ping | 連接保持活動狀態 | 每 10 秒發送一次 |
錯誤響應
| 狀態 | 代碼 | 描述 |
|---|---|---|
| 400 | invalid_param | 請求中的參數無效 |
| 400 | app_unavailable | 應用配置不可用 |
| 400 | provider_not_initialize | 沒有可用的模型憑證配置 |
| 400 | provider_quota_exceeded | 模型調用配額已超出 |
| 400 | model_currently_not_support | 當前模型不可用 |
| 400 | completion_request_error | 文本生成失敗 |
| 500 | - | 內部服務器錯誤 |
支持的端點
文件上傳端點
- URL：
/files/upload - 方法：POST
- 目的：上傳文件（目前支持圖像）以用于文本生成消息
- Content-Type：multipart/form-data
請求參數：
| 參數 | 類型 | 必填 | 描述 |
|---|---|---|---|
| file | file | 是 | 要上傳的文件 |
| user | string | 是 | 與文本生成消息中使用的用戶標識符匹配的用戶標識符 |
響應：
{"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67","name": "example.png","size": 1024,"extension": "png","mime_type": "image/png","created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13","created_at": 1577836800
}
停止生成端點
- URL：
/completion-messages/:task_id/stop - 方法：POST
- 目的：停止正在進行的文本生成過程（僅流式模式）
請求參數：
| 參數 | 類型 | 必填 | 描述 |
|---|---|---|---|
| user | string | 是 | 與文本生成消息中使用的用戶標識符匹配的用戶標識符 |
響應：
{"result": "success"
}
消息反饋端點
- URL：
/messages/:message_id/feedbacks - 方法：POST
- 目的：對生成的內容提供反饋（點贊、點踩、評論）
請求參數：
| 參數 | 類型 | 必填 | 描述 |
|---|---|---|---|
| rating | string | 是 | “like”、“dislike” 或 null（撤銷評分） |
| user | string | 是 | 用戶標識符 |
| content | string | 否 | 詳細的反饋內容 |
響應：
{"result": "success"
}
文本轉語音端點
- URL：
/text-to-audio - 方法：POST
- 目的：將文本轉換為語音音頻
請求參數：
| 參數 | 類型 | 必填 | 描述 |
|---|---|---|---|
| message_id | string | 否 | 要轉換為音頻的先前生成的消息 ID |
| text | string | 否 | 要轉換的文本內容（如果未提供 message_id 則使用） |
| user | string | 是 | 用戶標識符 |
響應：API 直接返回音頻文件，Content-Type 為 audio/wav。
系統架構中的文本生成 API
以下圖表說明了文本生成 API 如何與 Dify 系統的其他組件集成：
請求 - 響應流程
以下圖表顯示了文本生成 API 的請求 - 響應流程：
與聊天 API 的主要區別
| 功能 | 文本生成 API | 聊天 API |
|---|---|---|
| 會話持久性 | 無 | 有 |
| 對話歷史記錄 | 不維護 | 維護 |
| 用例 | 一次性文本生成（翻譯、摘要） | 交互式對話 |
| 主要端點 | /completion-messages | /chat-messages |
| 對話 ID | 不使用 | 繼續對話時需要 |
實現注意事項
- 流式響應使用服務器發送事件（SSE）格式。
- 響應內容可能會受到審核，不適當的內容會通過
message_replace事件進行替換。 - Cloudflare 超時限制請求為 100 秒。
- 文件上傳目前僅支持圖像文件（png, jpg, jpeg, webp, gif）。
- 在文本生成請求中使用文件時，請確保模型支持視覺功能。
錯誤處理
發生錯誤時，API 返回適當的 HTTP 狀態碼和錯誤信息：
- 對于阻塞模式請求，錯誤信息直接在 HTTP 響應中返回。
- 對于流式模式請求，錯誤作為 SSE 事件發送，事件類型為 error。
常見的錯誤場景包括：
- 無效參數（400）
- 應用配置問題（400）
- 模型提供方初始化問題（400）
- 配額超出錯誤（400）
- 不支持的模型（400）
- 文本生成失敗（400）
- 內部服務器錯誤（500）
RotSpecial)
