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

langgenius/dify

菜单

完成 API 端点

相关源文件

本文档介绍了 Dify 的 Completion 应用的 REST API 端点，这些应用提供文本生成能力，且无需会话持久化。Completion 应用专为单轮交互而设计，例如翻译、内容撰写、摘要以及其他文本转换任务。

对于具有会话历史的聊天应用，请参阅 Chat API 端点。对于基于工作流的应用，请参阅 Workflow API 端点。

概述

Dify 中的 Completion 应用是无状态的文本生成服务，它们处理输入并返回生成的内​​容，而不维护对话上下文。与聊天应用不同，它们不支持对话会话或消息历史。

应用程序架构

来源：web/app/components/develop/template/template.en.mdx1-670

核心端点

文本生成

POST /completion-messages

文本生成请求的主要端点。接收输入变量并返回生成的内​​容。

参数类型必填描述
inputs对象是变量值，包括必需的 query 字段
response_mode字符串是streaming 或 blocking
user字符串是最终用户标识符
filesarray否用于多模态输入的附件文件

请求流程

响应事件（流式传输）

  • message - 来自 LLM 的文本块
  • message_end - 生成完成，包含元数据
  • tts_message - 语音合成块（如果已启用）
  • tts_message_end - 语音合成完成
  • message_replace - 内容审核替换
  • error - 错误情况
  • ping - 心跳事件

来源：web/app/components/develop/template/template.en.mdx32-140

文件上传

POST /files/upload

处理用于多模态完成的文件上传。目前支持用于视觉模型的图像。

参数类型必填描述
filefile是要上传的文件
user字符串是用户标识符

支持的格式：PNG、JPG、JPEG、WEBP、GIF

响应包含文件 ID，可在 Completion 请求中通过 upload_file_id 参数使用。

来源：web/app/components/develop/template/template.en.mdx183-253

生成控制

POST /completion-messages/:task_id/stop

停止正在进行的流式文本生成。仅在流式模式下可用。

参数类型必填描述
task_id字符串是来自流式响应的任务 ID
user字符串是用户标识符

来源：web/app/components/develop/template/template.en.mdx255-294

响应模式

阻塞模式响应

流式模式事件

事件序列

  1. 多个 message 事件，包含文本块
  2. 可选的 tts_message 事件用于语音合成
  3. 最终的 message_end 事件，包含使用情况元数据

来源：web/app/components/develop/template/template.en.mdx160-198

反馈和分析

消息反馈

POST /messages/:message_id/feedbacks

收集用户对生成内容的反馈，以提高质量。

参数类型描述
rating字符串like, dislike, 或 null
user字符串用户标识符
content字符串反馈文本

应用反馈

GET /app/feedbacks

检索应用的反馈数据，支持分页。

参数类型描述
page字符串页码（默认为 1）
limit字符串每页记录数（默认为 20）

来源：web/app/components/develop/template/template.en.mdx296-419

辅助端点

文本转语音

POST /text-to-audio

将生成的文本转换为音频格式。

参数类型描述
message_id字符串要转换的消息 ID
text字符串文本内容（如果没有 message_id）
user字符串用户标识符

应用元数据

GET /info - 返回应用名称、描述和标签 GET /parameters - 返回输入参数和配置 GET /site - 返回 WebApp 显示设置

注释管理

GET /apps/annotations - 列出带分页的注释 POST /apps/annotations - 创建新注释 DELETE /apps/annotations/:id - 删除注释

来源：web/app/components/develop/template/template.en.mdx421-670

错误处理

常见的错误响应

代码错误描述
400invalid_param无效的请求参数
400app_unavailable应用未配置
400provider_not_initialize无模型凭证
400provider_quota_exceeded已超出使用配额
400completion_request_error文本生成失败
500内部服务器错误系统错误

来源：web/app/components/develop/template/template.en.mdx131-139