本文档提供了有关 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)
