在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

langgenius/dify

菜单

聊天 API 端点

相关源文件

本文档提供了 Dify 中 Chat API 端点的全面文档。这些端点使开发人员能够将聊天功能集成到他们的应用程序中，从而实现会话持久化和上下文感知对话。有关 Completion API 端点（非对话式文本生成），请参阅 Completion API 端点。

概述

Dify 中的 Chat API 提供了用于创建和管理与 AI 模型进行对话交互的端点。这些端点支持流式传输和阻塞响应模式、用于多模态交互的文件上传、会话管理和用户反馈机制。

Chat API 端点概述

来源： web/app/components/develop/template/template_chat.en.mdx32-37
web/app/components/develop/template/template_chat.zh.mdx30-35
web/app/components/develop/template/template_chat.en.mdx273-278
web/app/components/develop/template/template_chat.en.mdx390-395
web/app/components/develop/template/template_chat.en.mdx516-521

身份验证

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

Authorization: Bearer {API_KEY}

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

来源： web/app/components/develop/template/template_chat.en.mdx15-27
web/app/components/develop/template/template_chat.zh.mdx15-26

关键 API 端点

发送聊天消息

POST /chat-messages

此端点创建一个新的聊天消息，可以选择继续现有对话。

请求参数

参数类型必填描述
query字符串是用户输入/问题内容
inputs对象否App 定义的变量值，键值对形式
response_mode字符串是streaming (SSE 类似打字机的输出) 或 blocking (等待完成)
user字符串是最终用户的唯一标识符
conversation_id字符串否要继续的对话 ID
filesarray[object]否要随消息包含的文件（图像、文档等）
auto_generate_name布尔值否是否为对话自动生成标题

files 数组可以包含具有以下结构的对象的元素

或者：

响应

响应根据 response_mode 不同而不同

  1. 当 response_mode 为 blocking 时，会返回一个完整的 ChatCompletionResponse 对象。
  2. 当 response_mode 为 streaming 时，将使用 Server-Sent Events (SSE) 返回 ChunkChatCompletionResponse 对象流。
阻塞模式响应结构
流式传输模式事件

在流式传输模式下，可以返回不同的事件类型

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

来源： web/app/components/develop/template/template_chat.en.mdx30-305
web/app/components/develop/template/template_chat.zh.mdx30-267

文件上传

POST /files/upload

此端点允许上传文件（目前主要针对图像）以用于多模态对话。

请求参数

此端点使用 multipart/form-data 编码

参数类型必填描述
file文件是要上传的文件
user字符串是用户标识符（必须与聊天请求中的用户匹配）

响应

来源： web/app/components/develop/template/template_chat.en.mdx272-344
web/app/components/develop/template/template_chat.zh.mdx289-361

停止生成

POST /chat-messages/:task_id/stop

此端点可停止正在进行的流式传输生成。

路径参数

参数类型描述
task_id字符串来自流式响应的任务 ID

请求体

参数类型必填描述
user字符串是用户标识符（必须与开始生成的请求匹配）

响应

来源： web/app/components/develop/template/template_chat.en.mdx346-386
web/app/components/develop/template/template_zh.mdx362-401

消息反馈

POST /messages/:message_id/feedbacks

此端点允许最终用户提供对消息的反馈。

路径参数

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

请求体

参数类型必填描述
rating字符串是"like"（点赞）、"dislike"（点踩）或 null（取消点赞）
user字符串是用户标识符
content字符串否具体的反馈内容

响应

来源： web/app/components/develop/template/template_chat.en.mdx388-449
web/app/components/develop/template/template_chat.zh.mdx403-463

获取建议问题

GET /messages/{message_id}/suggested

此端点返回对消息的建议后续问题。

路径参数

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

查询参数

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

响应

来源： web/app/components/develop/template/template_chat.en.mdx451-504
web/app/components/develop/template/template_chat.zh.mdx465-517

获取对话历史消息

GET /messages

此端点返回对话的消息历史记录。

查询参数

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

响应结构

来源： web/app/components/develop/template/template_chat.en.mdx506-612
web/app/components/develop/template/template_chat.zh.mdx521-626

获取对话列表

GET /conversations

此端点检索当前用户对话的列表。

查询参数

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

响应结构

来源： web/app/components/develop/template/template_chat.en.mdx614-756
web/app/components/develop/template/template_chat.zh.mdx628-756

删除对话

DELETE /conversations/:conversation_id

此端点删除一个对话。

路径参数

参数类型描述
conversation_id字符串要删除的对话 ID

请求体

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

响应

来源： web/app/components/develop/template/template_chat.en.mdx758-804
web/app/components/develop/template/template_chat.zh.mdx758-794

系统架构

Chat API 组件图

来源： web/app/components/develop/template/template_chat.en.mdx1-200
web/app/components/develop/template/template_chat.zh.mdx1-200
web/app/components/develop/template/template_advanced_chat.en.mdx1-150

聊天消息流

来源： web/app/components/develop/template/template_chat.en.mdx30-270
web/app/components/develop/template/template_chat.zh.mdx30-267

错误处理

Chat API 端点返回标准的 HTTP 状态码以指示成功或失败

状态码错误代码描述
400invalid_param无效参数输入
400app_unavailable应用程序配置不可用
400provider_not_initialize没有可用的模型凭据配置
400provider_quota_exceeded已超出模型调用配额
400model_currently_not_support当前模型不可用
400completion_request_error文本生成失败
404-对话不存在
500-Internal server error

对于文件上传，其他错误代码包括

状态码错误代码描述
400no_file_uploaded未提供文件
400too_many_files仅接受一个文件
400unsupported_preview文件不支持预览
400unsupported_estimate文件不支持估算
413file_too_large文件过大
415unsupported_file_type不支持的文件扩展名
503s3_connection_failed无法连接到存储服务
503s3_permission_denied无权上传文件
503s3_file_too_large文件超出存储大小限制

来源： web/app/components/develop/template/template_chat.en.mdx170-178
web/app/components/develop/template/template_chat.zh.mdx171-179
web/app/components/develop/template/template_chat.en.mdx310-312
web/app/components/develop/template/template_chat.zh.mdx323-332

支持的文件类型

对于多模态交互，Chat API 支持多种文件类型

图像文件

  • JPG/JPEG
  • PNG
  • GIF
  • WEBP
  • SVG

文档文件（高级聊天）

  • TXT
  • MD/MARKDOWN
  • PDF
  • HTML
  • XLSX/XLS
  • DOCX
  • CSV
  • EML
  • MSG
  • PPTX/PPT
  • XML
  • EPUB

媒体文件（高级聊天）

  • MP3
  • M4A
  • WAV
  • WEBM
  • AMR
  • MP4
  • MOV
  • MPEG
  • MPGA

来源： web/app/components/develop/template/template_advanced_chat.en.mdx69-74
web/app/components/develop/template/template_workflow.en.mdx49-54

与 Dify 核心系统的集成

Chat API 端点与 Dify 的几个核心系统集成

  1. 对话系统：管理对话状态和历史记录
  2. RAG 知识系统：从知识库中检索相关信息
  3. 模型提供商系统：连接到各种 LLM 提供商
  4. 工作流系统：在使用高级聊天时协调复杂的人工智能工作流

基本聊天和代理聊天应用程序的端点遵循相似的模式，但具有不同的功能。

来源： web/app/components/develop/template/template_chat.en.mdx1-100
web/app/components/develop/template/template_advanced_chat.en.mdx1-100