Dify-13: 文本生成API端点

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