当前位置：首页 > news >正文

Dify-13: 文本生成API端点

news 2025/7/23 15:26:26

本文档提供了有关 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	不使用	继续对话时需要