Dify-12: 聊天应用API端点

本文档提供了 Dify 中聊天 API 端点的全面文档。这些端点使开发人员能够将聊天功能集成到他们的应用程序中，支持会话持久性和上下文感知对话。

概述

Dify 中的聊天 API 提供了用于创建和管理与人工智能模型的对话交互的端点。这些端点支持流式和阻塞式响应模式、用于多模态交互的文件上传、对话管理以及用户反馈机制。

聊天 API 端点

• 创建消息
• 停止生成
• 上传文件
• 用户反馈
• 获取历史记录
• 列出对话
• 删除对话
• 获取建议

端点	用途
/chat-messages	聊天流程
/chat-messages/:task_id/stop	停止生成
/files/upload	上传文件
/messages/:message_id/feedbacks	用户反馈
/messages	获取对话历史记录
/conversations	列出对话
/conversations/:id	管理对话（如删除）
/messages/:id/suggested	获取建议问题

身份验证

所有 API 端点都需要 API 密钥进行身份验证。API 密钥必须使用承载方案包含在 Authorization HTTP 标头中：

Authorization: Bearer {API_KEY}

重要提示：API 密钥应安全存储在服务器端，绝不要在客户端代码中暴露，以防止未经授权的访问。

关键 API 端点

发送聊天消息

端点：POST /chat-messages
此端点创建新的聊天消息，也可选择继续现有对话。

请求参数：

参数	类型	必填	描述
query	string	是	用户输入 / 问题内容
inputs	object	否	应用定义的变量值，以键值对形式
response_mode	string	是	“streaming”（类似打字机输出的流式模式）或 “blocking”（等待完成）
user	string	是	终端用户的唯一标识符
conversation_id	string	否	要继续的对话 ID
files	array[object]	否	要包含在消息中的文件（图像、文档等）
auto_generate_name	boolean	否	是否自动生成对话标题

files 数组可以包含以下结构的对象：

{
  "type": "image", 
  "transfer_method": "remote_url", 
  "url": "https://example.com/image.png"
}

或：

{
  "type": "image", 
  "transfer_method": "local_file", 
  "upload_file_id": "72fa9618-8f89-4a37-9b33-7e1178a24a67"
}

响应：
响应根据 response_mode 而不同：

• 当 response_mode 为 “blocking” 时，返回完整的 ChatCompletionResponse 对象。
• 当 response_mode 为 “streaming” 时，使用服务器发送事件（SSE）返回 ChunkChatCompletionResponse 对象流。

阻塞模式响应结构：

{
  "event": "message",
  "task_id": "c3800678-a076-43df-a102-53f23ed20b88", 
  "id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
  "mode": "chat",
  "answer": "响应内容...",
  "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
    },
    "retriever_resources": [
      // 对检索到的知识的引用
    ]
  },
  "created_at": 1705407629
}

流式模式事件：
在流式模式下，可能返回不同的事件类型：

事件类型	描述
message	来自大语言模型的文本块
agent_message	智能体模式下的文本块
agent_thought	智能体的思考步骤和工具调用（在智能体模式下）
message_file	工具创建的新文件
message_end	流式消息结束
tts_message	文本转语音音频块（启用时）
tts_message_end	文本转语音音频流结束
message_replace	内容替换（触发审核时）
error	错误信息
ping	保持连接的 ping 事件

文件上传

端点：POST /files/upload
此端点允许上传文件（目前主要是图像）以用于多模态对话。

请求参数：
此端点使用 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
}

停止生成

端点：POST /chat-messages/:task_id/stop
此端点停止正在进行的流式生成。

路径参数：

参数	类型	描述
task_id	string	流式响应中的任务 ID

请求体：

参数	类型	必填	描述
user	string	是	用户标识符（必须与启动生成的请求匹配）

响应：

{
  "result": "success"
}

消息反馈

端点：POST /messages/:message_id/feedbacks
此端点允许终端用户对消息提供反馈。

路径参数：

参数	类型	描述
message_id	string	要提供反馈的消息 ID

请求体：

参数	类型	必填	描述
rating	string	是	“like”（点赞）、“dislike”（点踩）或 null（撤销点赞）
user	string	是	用户标识符
content	string	否	具体的反馈内容

响应：

{
  "result": "success"
}

获取建议问题

端点：GET /messages/{message_id}/suggested
此端点返回某条消息的建议后续问题。

路径参数：

参数	类型	描述
message_id	string	要获取建议的消息 ID

查询参数：

参数	类型	必填	描述
user	string	是	用户标识符

响应：

{
  "result": "success",
  "data": [
    "建议问题 1",
    "建议问题 2",
    "建议问题 3"
  ]
}

获取对话历史消息

端点：GET /messages
此端点返回对话的消息历史记录。

查询参数：

参数	类型	必填	描述
conversation_id	string	是	对话 ID
user	string	是	用户标识符
first_id	string	否	当前页面的第一条消息 ID
limit	integer	否	返回的消息数量（默认：20）

响应结构：

{
  "limit": 20,
  "has_more": false,
  "data": [
    {
      "id": "a076a87f-31e5-48dc-b452-0061adbbc922",
      "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
      "inputs": { "name": "dify" },
      "query": "Hello, world!",
      "answer": "Hello! How can I help you today?",
      "message_files": [],
      "feedback": null,
      "retriever_resources": [],
      "agent_thoughts": [],
      "created_at": 1705569239
    }
    // 更多消息...
  ]
}

获取对话列表

端点：GET /conversations
此端点检索当前用户的对话列表。

查询参数：

参数	类型	必填	描述
user	string	是	用户标识符
last_id	string	否	当前页面最后一条记录的 ID
limit	integer	否	返回的记录数量（默认：20，最大：100）
sort_by	string	否	排序字段（created_at, -created_at, updated_at, -updated_at）

响应结构：

{
  "limit": 20,
  "has_more": false,
  "data": [
    {
      "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54",
      "name": "New chat",
      "inputs": {
        "book": "book",
        "myName": "Lucy"
      },
      "status": "normal",
      "created_at": 1679667915,
      "updated_at": 1679667915
    }
    // 更多对话...
  ]
}

删除对话

端点：DELETE /conversations/:conversation_id
此端点删除对话。

路径参数：

参数	类型	描述
conversation_id	string	要删除的对话 ID

请求体：

参数	类型	必填	描述
user	string	是	用户标识符

响应：

{
  "result": "success"
}

系统架构

聊天 API 组件图

聊天消息流程