Dify 后端 API 版本0.15

Dify 通用接口文

目录

---

档

一、接口概述

本文档描述了Dify应用的通用接口规范，包括参数定义、错误处理等内容。所有接口都遵循RESTful设计规范。

二、通用参数定义

1. 系统参数

系统参数定义了一些全局的限制和配置：

{ "system_parameters": { "image_file_size_limit": 10485760, // 图片文件大小限制（字节） "video_file_size_limit": 31457280, // 视频文件大小限制（字节） "audio_file_size_limit": 31457280, // 音频文件大小限制（字节） "file_size_limit": 31457280, // 普通文件大小限制（字节） "workflow_file_upload_limit": 10485760 // 工作流文件上传限制（字节） } }

2. 功能参数

功能参数定义了各种功能的配置：

2.1 基础字段定义

{ "opening_statement": "开场白文本", "suggested_questions": [ // 建议问题列表 { "question": "问题文本", "type": "问题类型" } ], "suggested_questions_after_answer": { // 回答后的建议问题 "enabled": false, "questions": [] }, "speech_to_text": { // 语音转文本 "enabled": false, "provider": "提供商", "language": "语言" }, "text_to_speech": { // 文本转语音 "enabled": false, "provider": "提供商", "voice": "语音" }, "retriever_resource": { // 检索资源 "enabled": false, "type": "检索类型" }, "annotation_reply": { // 注释回复 "enabled": false, "rules": [] }, "more_like_this": { // 相似推荐 "enabled": false, "k": 3 } }

2.2 高级字段定义

{ "user_input_form": [ // 用户输入表单 { "text-input": { "label": "标签", "variable": "变量名", "required": true, "default": "默认值" } } ], "sensitive_word_avoidance": { // 敏感词过滤 "enabled": false, "type": "过滤类型", "configs": [ { "words": ["敏感词1", "敏感词2"], "action": "处理动作" } ] }, "file_upload": { // 文件上传 "image": { "enabled": false, "number_limits": 3, "detail": "high", "transfer_methods": ["remote_url", "local_file"], "formats": ["jpg", "png", "gif"] }, "video": { "enabled": false, "number_limits": 1, "transfer_methods": ["remote_url"] }, "audio": { "enabled": false, "number_limits": 1, "transfer_methods": ["local_file"] } } }

三、文件处理

1. 文件信息

文件信息包含以下字段：

{ "filename": "文件名", "extension": "文件扩展名", "mimetype": "文件MIME类型", "size": "文件大小（字节）" }

2. 文件上传方式

支持两种文件上传方式： - 本地文件上传（local_file） - 远程URL上传（remote_url）

3. 文件处理工具函数

系统提供了以下文件处理工具函数：

3.1 从响应中获取文件信息

从HTTP响应中提取文件信息，包括： - 从URL中提取文件名 - 从Content-Disposition头中提取文件名 - 自动生成唯一文件名 - 猜测MIME类型 - 获取文件大小

3.2 从特征字典中获取参数

从特征字典中提取参数，包括： - 开场白 - 建议问题 - 语音转文本配置 - 文本转语音配置 - 检索资源配置 - 注释回复配置 - 相似推荐配置 - 用户输入表单 - 敏感词过滤配置 - 文件上传配置 - 系统参数配置

四、错误处理

1. 错误响应格式

所有错误响应都遵循以下格式：

{ "error": { "code": 400, "message": "错误描述信息" } }

2. 通用错误类型

• FilenameNotExistsError

• 状态码：400

• 描述：指定的文件名不存在

• 场景：上传文件时未指定文件名

• RemoteFileUploadError

• 状态码：400

• 描述：远程文件上传错误

• 场景：通过URL上传文件失败

五、注意事项

1. 所有文件大小限制均以字节为单位

2. 文件上传时需要注意文件类型和大小限制

3. 远程文件上传时需要确保URL可访问且文件格式合法

4. 敏感词过滤功能需要在配置中明确启用

5. 所有布尔类型的功能配置默认为false Dify 控制台 API 接口文档

一、接口概述

本文档描述了Dify控制台的API接口，包括系统管理、应用管理、文件管理等功能。所有接口都遵循RESTful设计规范。

二、认证方式

1. 登录认证

大部分接口需要用户登录认证，需要在HTTP请求头中包含认证信息：

Authorization: Bearer your-token

2. 管理员认证

某些管理员接口需要管理员权限，需要在HTTP请求头中包含管理员API密钥：

Authorization: Bearer admin-api-key

三、文档目录

1. 基础接口文档 - 本文档,包含概述和认证说明

2. 系统接口文档 - 系统相关接口

3. 用户接口文档 - 用户管理相关接口

4. 应用接口文档 - 应用管理相关接口

5. 数据集接口文档 - 数据集管理相关接口

6. 文件接口文档 - 文件管理相关接口

7. 会话接口文档 - 会话管理相关接口

8. 消息接口文档 - 消息管理相关接口

9. 账单接口文档 - 账单和支付相关接口

10. 工作区接口文档 - 工作区管理相关接口

11. 统计接口文档 - 统计分析相关接口

12. 错误码文档 - 错误码说明文档 Dify 控制台应用接口文档

Dify 控制台 API 接口文档

一、接口概述

本文档描述了Dify控制台的API接口，包括系统管理、应用管理、文件管理等功能。所有接口都遵循RESTful设计规范。

二、认证方式

1. 登录认证

大部分接口需要用户登录认证，需要在HTTP请求头中包含认证信息：

Authorization: Bearer your-token

2. 管理员认证

某些管理员接口需要管理员权限，需要在HTTP请求头中包含管理员API密钥：

Authorization: Bearer admin-api-key

三、文档目录

1. 基础接口文档 - 本文档,包含概述和认证说明

2. 系统接口文档 - 系统相关接口

3. 用户接口文档 - 用户管理相关接口

4. 应用接口文档 - 应用管理相关接口

5. 数据集接口文档 - 数据集管理相关接口

6. 文件接口文档 - 文件管理相关接口

7. 会话接口文档 - 会话管理相关接口

8. 消息接口文档 - 消息管理相关接口

9. 账单接口文档 - 账单和支付相关接口

10. 工作区接口文档 - 工作区管理相关接口

11. 统计接口文档 - 统计分析相关接口

12. 错误码文档 - 错误码说明文档 Dify 控制台系统接口文档

系统相关接口

1. 系统状态检查

• 接口地址：/console/api/ping

• 请求方法：GET

• 认证方式：无需认证

• 响应示例：

{ "result": "pong" }

2. 版本检查

• 接口地址：/console/api/version

• 请求方法：GET

• 认证方式：无需认证

• 请求参数：

• current_version（必需）：当前版本号

• 响应示例：

{ "version": "0.3.0", "release_date": "2023-12-25", "release_notes": "版本更新说明", "can_auto_update": false, "features": { "can_replace_logo": true, "model_load_balancing_enabled": true } }

3. 获取系统功能特性

• 接口地址：/console/api/system-features

• 请求方法：GET

• 认证方式：无需认证

• 响应示例：

{ "features": { "can_replace_logo": true, "model_load_balancing_enabled": true } }

4. 初始化验证

• 接口地址：/console/api/init

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• password（必需）：初始化密码

• 响应示例：

{ "result": "success" }

5. 系统设置

• 接口地址：/console/api/setup

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• email（必需）：管理员邮箱

• name（必需）：管理员名称

• password（必需）：管理员密码

• 响应示例：

{ "result": "success" }

6. 获取系统状态

• 接口地址：/console/api/system/status

• 请求方法：GET

• 认证方式：需要管理员权限

• 响应示例：

{ "version": "系统版本", "environment": "运行环境", "database_status": "数据库状态", "cache_status": "缓存状态", "storage_status": "存储状态" }

7. 获取系统配置

• 接口地址：/console/api/system/configuration

• 请求方法：GET

• 认证方式：需要管理员权限

• 响应示例：

{ "site_name": "站点名称", "site_url": "站点URL", "mail_server": "邮件服务器配置", "storage_provider": "存储提供商配置", "features": { "registration_enabled": true, "social_login_enabled": true } }

8. 更新系统配置

• 接口地址：/console/api/system/configuration

• 请求方法：POST

• 认证方式：需要管理员权限

• 请求参数：

• site_name：站点名称

• site_url：站点URL

• mail_server：邮件服务器配置

• storage_provider：存储提供商配置

• features：功能开关配置

• 响应示例：

{ "result": "success" }Dify 控制台用户接口文档

用户认证接口

1. 用户登录

• 接口地址：/console/api/auth/login

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• email（必需）：用户邮箱

• password（必需）：用户密码

• remember_me：是否记住登录状态

• 响应示例：

{ "access_token": "访问令牌", "refresh_token": "刷新令牌", "expires_in": 3600, "token_type": "Bearer" }

2. 用户注册

• 接口地址：/console/api/auth/register

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• email（必需）：用户邮箱

• name（必需）：用户名称

• password（必需）：用户密码

• invite_code：邀请码

• 响应示例：

{ "result": "success" }

3. 账户激活

• 接口地址：/console/api/auth/activate

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• token（必需）：激活令牌

• 响应示例：

{ "result": "success" }

4. 重新发送激活邮件

• 接口地址：/console/api/auth/resend-activation

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• email（必需）：用户邮箱

• 响应示例：

{ "result": "success" }

5. 忘记密码

• 接口地址：/console/api/auth/forgot-password

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• email（必需）：用户邮箱

• 响应示例：

{ "result": "success" }

6. 重置密码

• 接口地址：/console/api/auth/reset-password

• 请求方法：POST

• 认证方式：无需认证

• 请求参数：

• token（必需）：重置令牌

• new_password（必需）：新密码

• 响应示例：

{ "result": "success" }

7. 刷新令牌

• 接口地址：/console/api/auth/refresh

• 请求方法：POST

• 认证方式：需要刷新令牌

• 请求参数：

• refresh_token（必需）：刷新令牌

• 响应示例：

{ "access_token": "新访问令牌", "refresh_token": "新刷新令牌", "expires_in": 3600, "token_type": "Bearer" }

8. 退出登录

• 接口地址：/console/api/auth/logout

• 请求方法：POST

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success" }

OAuth认证接口

1. OAuth授权

• 接口地址：/console/api/oauth/authorize

• 请求方法：GET

• 认证方式：无需认证

• 请求参数：

• provider（必需）：OAuth提供商

• redirect_uri：回调地址

• state：状态参数

• 响应示例：

{ "authorization_url": "授权URL" }

2. OAuth回调

• 接口地址：/console/api/oauth/callback

• 请求方法：GET

• 认证方式：无需认证

• 请求参数：

• code：授权码

• state：状态参数

• 响应示例：

{ "access_token": "访问令牌", "refresh_token": "刷新令牌", "expires_in": 3600, "token_type": "Bearer" }

数据源认证接口

1. 数据源Bearer认证

• 接口地址：/console/api/auth/data-source/bearer

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• provider（必需）：数据源提供商

• token（必需）：Bearer令牌

• 响应示例：

{ "result": "success", "data_source_id": "数据源ID" }

2. 数据源OAuth认证

• 接口地址：/console/api/auth/data-source/oauth

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• provider（必需）：数据源提供商

• code（必需）：授权码

• redirect_uri：回调地址

• 响应示例：

{ "result": "success", "data_source_id": "数据源ID" }

3. 数据源OAuth回调

• 接口地址：/console/api/auth/data-source/oauth/callback

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• provider：数据源提供商

• code：授权码

• state：状态参数

• 响应示例：

{ "result": "success", "data_source_id": "数据源ID" }

用户信息接口

1. 获取当前用户信息

• 接口地址：/console/api/users/current

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "id": "用户ID", "name": "用户名称", "email": "用户邮箱", "avatar": "头像URL", "role": "用户角色", "created_at": "2023-12-25T12:00:00Z" }

2. 更新用户信息

• 接口地址：/console/api/users/current

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• name：用户名称

• avatar：头像URL

• 响应示例：

{ "id": "用户ID", "name": "用户名称", "email": "用户邮箱", "avatar": "头像URL", "updated_at": "2023-12-25T12:00:00Z" }

3. 修改密码

• 接口地址：/console/api/users/password

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• current_password（必需）：当前密码

• new_password（必需）：新密码

• 响应示例：

{ "result": "success" }

个人设置接口

1. 获取个人设置

• 接口地址：/console/api/settings/personal

• 请求方法：GET

• 认证方式：需要登录

• 响应示例：

{ "language": "界面语言", "theme": "界面主题", "timezone": "时区设置", "notification_settings": { "email_enabled": true, "browser_enabled": true } }

2. 更新个人设置

• 接口地址：/console/api/settings/personal

• 请求方法：PATCH

• 认证方式：需要登录

• 请求参数：

• language：界面语言

• theme：界面主题

• timezone：时区设置

• notification_settings：通知设置

• 响应示例：

{ "result": "success" }Dify 控制台应用接口文档

应用管理接口

1. 获取应用列表

• 接口地址：/console/api/apps

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• type：应用类型

• status：应用状态

• 响应示例：

{ "data": [ { "id": "应用ID", "name": "应用名称", "type": "应用类型", "status": "应用状态", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

2. 创建应用

• 接口地址：/console/api/apps

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• name（必需）：应用名称

• type（必需）：应用类型

• mode：应用模式

• icon：应用图标

• description：应用描述

• 响应示例：

{ "id": "应用ID", "name": "应用名称", "type": "应用类型", "mode": "应用模式", "created_at": "2023-12-25T12:00:00Z" }

3. 获取应用详情

• 接口地址：/console/api/apps/<app_id>

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "id": "应用ID", "name": "应用名称", "type": "应用类型", "mode": "应用模式", "icon": "应用图标", "description": "应用描述", "api_base_url": "API基础URL", "created_at": "2023-12-25T12:00:00Z", "updated_at": "2023-12-25T12:00:00Z" }

4. 更新应用

• 接口地址：/console/api/apps/<app_id>

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• name：应用名称

• type：应用类型

• mode：应用模式

• icon：应用图标

• description：应用描述

• 响应示例：

{ "result": "success" }

5. 删除应用

• 接口地址：/console/api/apps/<app_id>

• 请求方法：DELETE

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success" }

6. 获取应用配置

• 接口地址：/console/api/apps/<app_id>/configuration

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "model": { "provider": "模型提供商", "name": "模型名称", "parameters": { "temperature": 0.7, "max_tokens": 2000 } }, "features": { "enable_debug": true, "enable_log": true, "enable_moderation": false } }

7. 更新应用配置

• 接口地址：/console/api/apps/<app_id>/configuration

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• model：模型配置

• features：功能配置

• 响应示例：

{ "result": "success" }

8. 获取应用API密钥

• 接口地址：/console/api/apps/<app_id>/api-keys

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "data": [ { "id": "密钥ID", "name": "密钥名称", "key": "API密钥", "created_at": "2023-12-25T12:00:00Z" } ] }

9. 创建应用API密钥

• 接口地址：/console/api/apps/<app_id>/api-keys

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• name（必需）：密钥名称

• 响应示例：

{ "id": "密钥ID", "name": "密钥名称", "key": "API密钥", "created_at": "2023-12-25T12:00:00Z" }

10. 删除应用API密钥

• 接口地址：/console/api/apps/<app_id>/api-keys/<key_id>

• 请求方法：DELETE

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success" }

11. 更新应用图标

• 接口地址：/console/api/apps/<app_id>/icon

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• icon_type：图标类型

• icon：图标

• icon_background：图标背景色

• 响应示例：

{ "result": "success" }

12. 更新应用站点状态

• 接口地址：/console/api/apps/<app_id>/site-status

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• status：站点状态

• 响应示例：

{ "result": "success" }

13. 更新应用API状态

• 接口地址：/console/api/apps/<app_id>/api-status

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• status：API状态

• 响应示例：

{ "result": "success" }Dify 控制台数据集接口文档

数据集管理接口

1. 获取数据集列表

• 接口地址：/console/api/datasets

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• keyword：搜索关键词

• 响应示例：

{ "data": [ { "id": "数据集ID", "name": "数据集名称", "description": "数据集描述", "provider": "数据源提供商", "permission": "权限设置", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

2. 创建数据集

• 接口地址：/console/api/datasets

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• name（必需）：数据集名称

• description：数据集描述

• provider（必需）：数据源提供商

• permission：权限设置

• indexing_technique：索引技术

• retrieval_technique：检索技术

• 响应示例：

{ "id": "数据集ID", "name": "数据集名称", "description": "数据集描述", "provider": "数据源提供商", "created_at": "2023-12-25T12:00:00Z" }

3. 获取数据集详情

• 接口地址：/console/api/datasets/<dataset_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "数据集ID", "name": "数据集名称", "description": "数据集描述", "provider": "数据源提供商", "permission": "权限设置", "indexing_technique": "索引技术", "retrieval_technique": "检索技术", "created_at": "2023-12-25T12:00:00Z", "updated_at": "2023-12-25T12:00:00Z" }

4. 更新数据集

• 接口地址：/console/api/datasets/<dataset_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• name：数据集名称

• description：数据集描述

• permission：权限设置

• indexing_technique：索引技术

• retrieval_technique：检索技术

• 响应示例：

{ "result": "success" }

5. 删除数据集

• 接口地址：/console/api/datasets/<dataset_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

6. 获取数据集文档列表

• 接口地址：/console/api/datasets/<dataset_id>/documents

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• keyword：搜索关键词

• status：文档状态

• 响应示例：

{ "data": [ { "id": "文档ID", "name": "文档名称", "content": "文档内容", "status": "文档状态", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

7. 上传数据集文档

• 接口地址：/console/api/datasets/<dataset_id>/documents

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• file（必需）：文档文件

• name：文档名称

• process_rule：处理规则

• 响应示例：

{ "id": "文档ID", "name": "文档名称", "status": "处理中", "created_at": "2023-12-25T12:00:00Z" }

8. 获取文档详情

• 接口地址：/console/api/datasets/<dataset_id>/documents/<document_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "文档ID", "name": "文档名称", "content": "文档内容", "status": "文档状态", "created_at": "2023-12-25T12:00:00Z", "updated_at": "2023-12-25T12:00:00Z" }

9. 更新文档

• 接口地址：/console/api/datasets/<dataset_id>/documents/<document_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• name：文档名称

• content：文档内容

• process_rule：处理规则

• 响应示例：

{ "result": "success" }

10. 删除文档

• 接口地址：/console/api/datasets/<dataset_id>/documents/<document_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

11. 获取文档分段列表

• 接口地址：/console/api/datasets/<dataset_id>/documents/<document_id>/segments

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• 响应示例：

{ "data": [ { "id": "分段ID", "content": "分段内容", "position": "位置信息", "enabled": true, "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

12. 更新文档分段状态

• 接口地址：/console/api/datasets/<dataset_id>/documents/<document_id>/segments/<segment_id>/status

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• enabled（必需）：是否启用

• 响应示例：

{ "result": "success" }

13. 获取数据源列表

• 接口地址：/console/api/datasets/data-sources

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "data": [ { "id": "数据源ID", "name": "数据源名称", "provider": "提供商", "type": "数据源类型", "created_at": "2023-12-25T12:00:00Z" } ] }

14. 创建数据源

• 接口地址：/console/api/datasets/data-sources

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• name（必需）：数据源名称

• provider（必需）：提供商

• type（必需）：数据源类型

• config：配置信息

• 响应示例：

{ "id": "数据源ID", "name": "数据源名称", "provider": "提供商", "created_at": "2023-12-25T12:00:00Z" }

15. 更新数据源

• 接口地址：/console/api/datasets/data-sources/<source_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• name：数据源名称

• config：配置信息

• 响应示例：

{ "result": "success" }

16. 删除数据源

• 接口地址：/console/api/datasets/data-sources/<source_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

17. 同步数据源

• 接口地址：/console/api/datasets/data-sources/<source_id>/sync

• 请求方法：POST

• 认证方式：需要编辑者权限

• 响应示例：

{ "task_id": "同步任务ID", "status": "同步状态" }

18. 获取外部数据源列表

• 接口地址：/console/api/datasets/external-sources

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "data": [ { "id": "外部数据源ID", "name": "数据源名称", "provider": "提供商", "type": "数据源类型", "created_at": "2023-12-25T12:00:00Z" } ] }

19. 添加外部数据源

• 接口地址：/console/api/datasets/external-sources

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• name（必需）：数据源名称

• provider（必需）：提供商

• type（必需）：数据源类型

• config：配置信息

• 响应示例：

{ "id": "外部数据源ID", "name": "数据源名称", "provider": "提供商", "created_at": "2023-12-25T12:00:00Z" }

20. 获取网站数据源配置

• 接口地址：/console/api/datasets/website-configs

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "data": [ { "id": "配置ID", "url": "网站URL", "css_selector": "CSS选择器", "rules": ["抓取规则"], "created_at": "2023-12-25T12:00:00Z" } ] }

21. 添加网站数据源配置

• 接口地址：/console/api/datasets/website-configs

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• url（必需）：网站URL

• css_selector：CSS选择器

• rules：抓取规则

• 响应示例：

{ "id": "配置ID", "url": "网站URL", "created_at": "2023-12-25T12:00:00Z" }Dify 控制台文件接口文档

文件相关接口

1. 上传文件

• 接口地址：/console/api/files/upload

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• file（必需）：文件数据

• type（必需）：文件类型（audio, image, video, document）

• 响应示例：

{ "id": "文件ID", "name": "文件名称", "url": "文件URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" }

2. 预览文件

• 接口地址：/console/api/files/<file_id>/preview

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "文件ID", "name": "文件名称", "url": "文件URL", "preview_url": "预览URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" }

3. 获取远程文件信息

• 接口地址：/console/api/remote-files/<url>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "url": "文件URL", "name": "文件名称", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" }

4. 上传远程文件

• 接口地址：/console/api/remote-files/upload

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• url（必需）：远程文件URL

• type（必需）：文件类型（audio, image, video, document）

• 响应示例：

{ "id": "文件ID", "name": "文件名称", "url": "文件URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" }

5. 获取支持的文件类型

• 接口地址：/console/api/files/support-type

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "types": [ { "type": "文件类型", "extensions": ["扩展名列表"], "max_size": 10485760 } ] }

6. 删除文件

• 接口地址：/console/api/files/<file_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

7. 批量删除文件

• 接口地址：/console/api/files/batch

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 请求参数：

• file_ids（必需）：文件ID列表

• 响应示例：

{ "result": "success", "failed_ids": ["失败的文件ID列表"] }

8. 获取文件列表

• 接口地址：/console/api/files

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• type：文件类型

• keyword：搜索关键词

• 响应示例：

{ "data": [ { "id": "文件ID", "name": "文件名称", "url": "文件URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

9. 获取文件详情

• 接口地址：/console/api/files/<file_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "文件ID", "name": "文件名称", "url": "文件URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z", "metadata": { "width": 1920, "height": 1080, "duration": 60, "format": "文件格式" } }

10. 更新文件信息

• 接口地址：/console/api/files/<file_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• name：文件名称

• metadata：文件元数据

• 响应示例：

{ "id": "文件ID", "name": "文件名称", "url": "文件URL", "size": 1024, "mime_type": "文件MIME类型", "created_at": "2023-12-25T12:00:00Z" }Dify 控制台会话接口文档

会话管理接口

1. 获取会话列表

• 接口地址：/console/api/conversations

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• app_id：应用ID

• user_id：用户ID

• status：会话状态

• 响应示例：

{ "data": [ { "id": "会话ID", "name": "会话名称", "app_id": "应用ID", "user_id": "用户ID", "status": "会话状态", "created_at": "2023-12-25T12:00:00Z", "updated_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

2. 创建会话

• 接口地址：/console/api/conversations

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• app_id（必需）：应用ID

• name：会话名称

• variables：会话变量

• 响应示例：

{ "id": "会话ID", "name": "会话名称", "app_id": "应用ID", "created_at": "2023-12-25T12:00:00Z" }

3. 获取会话详情

• 接口地址：/console/api/conversations/<conversation_id>

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "id": "会话ID", "name": "会话名称", "app_id": "应用ID", "user_id": "用户ID", "status": "会话状态", "variables": { "key": "value" }, "created_at": "2023-12-25T12:00:00Z", "updated_at": "2023-12-25T12:00:00Z" }

4. 更新会话

• 接口地址：/console/api/conversations/<conversation_id>

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• name：会话名称

• variables：会话变量

• 响应示例：

{ "result": "success" }

5. 删除会话

• 接口地址：/console/api/conversations/<conversation_id>

• 请求方法：DELETE

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success" }

6. 获取会话消息列表

• 接口地址：/console/api/conversations/<conversation_id>/messages

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• 响应示例：

{ "data": [ { "id": "消息ID", "conversation_id": "会话ID", "role": "消息角色", "content": "消息内容", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

7. 发送会话消息

• 接口地址：/console/api/conversations/<conversation_id>/messages

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• content（必需）：消息内容

• role：消息角色（默认user）

• files：附件列表

• inputs：输入参数

• 响应示例：

{ "id": "消息ID", "conversation_id": "会话ID", "role": "消息角色", "content": "消息内容", "created_at": "2023-12-25T12:00:00Z" }

8. 重命名会话

• 接口地址：/console/api/conversations/<conversation_id>/name

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• name（必需）：新会话名称

• 响应示例：

{ "result": "success" }

9. 生成会话摘要

• 接口地址：/console/api/conversations/<conversation_id>/summary

• 请求方法：POST

• 认证方式：需要访问令牌

• 响应示例：

{ "summary": "会话摘要内容" }

10. 获取会话变量

• 接口地址：/console/api/conversations/<conversation_id>/variables

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "variables": { "key": "value" } }

11. 更新会话变量

• 接口地址：/console/api/conversations/<conversation_id>/variables

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• variables（必需）：新的变量值

• 响应示例：

{ "result": "success" }Dify 控制台消息接口文档

消息相关接口

1. 获取消息列表

• 接口地址：/console/api/messages

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• app_id：应用ID

• conversation_id：会话ID

• user_id：用户ID

• status：消息状态

• 响应示例：

{ "data": [ { "id": "消息ID", "conversation_id": "会话ID", "app_id": "应用ID", "user_id": "用户ID", "role": "消息角色", "content": "消息内容", "status": "消息状态", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

2. 发送消息

• 接口地址：/console/api/messages

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• conversation_id（必需）：会话ID

• content（必需）：消息内容

• role（必需）：消息角色（user, assistant）

• metadata：消息元数据

• inputs：输入参数

• query：查询内容

• files：关联文件列表

• 响应示例：

{ "id": "消息ID", "conversation_id": "会话ID", "role": "消息角色", "content": "消息内容", "status": "消息状态", "created_at": "2023-12-25T12:00:00Z" }

3. 获取消息详情

• 接口地址：/console/api/messages/<message_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "消息ID", "conversation_id": "会话ID", "app_id": "应用ID", "user_id": "用户ID", "role": "消息角色", "content": "消息内容", "status": "消息状态", "created_at": "2023-12-25T12:00:00Z", "metadata": { "tokens": 100, "finish_reason": "完成原因", "latency": 1000 } }

4. 更新消息

• 接口地址：/console/api/messages/<message_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• content：消息内容

• metadata：消息元数据

• status：消息状态

• 响应示例：

{ "id": "消息ID", "conversation_id": "会话ID", "role": "消息角色", "content": "消息内容", "status": "消息状态", "created_at": "2023-12-25T12:00:00Z" }

5. 删除消息

• 接口地址：/console/api/messages/<message_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

6. 获取消息反馈列表

• 接口地址：/console/api/messages/<message_id>/feedbacks

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "data": [ { "id": "反馈ID", "message_id": "消息ID", "rating": "评分", "content": "反馈内容", "created_at": "2023-12-25T12:00:00Z" } ] }

7. 添加消息反馈

• 接口地址：/console/api/messages/<message_id>/feedbacks

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• rating（必需）：评分（like, dislike）

• content：反馈内容

• 响应示例：

{ "id": "反馈ID", "message_id": "消息ID", "rating": "评分", "content": "反馈内容", "created_at": "2023-12-25T12:00:00Z" }

8. 获取消息统计信息

• 接口地址：/console/api/messages/<message_id>/statistics

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "tokens": 100, "latency": 1000, "feedback_count": 10, "positive_feedback_rate": 0.8, "created_at": "2023-12-25T12:00:00Z" }

9. 批量删除消息

• 接口地址：/console/api/messages/batch

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 请求参数：

• message_ids（必需）：消息ID列表

• 响应示例：

{ "result": "success", "failed_ids": ["失败的消息ID列表"] }

10. 获取消息模板列表

• 接口地址：/console/api/message-templates

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• app_id：应用ID

• type：模板类型

• 响应示例：

{ "data": [ { "id": "模板ID", "name": "模板名称", "content": "模板内容", "type": "模板类型", "created_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

11. 创建消息模板

• 接口地址：/console/api/message-templates

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• name（必需）：模板名称

• content（必需）：模板内容

• type（必需）：模板类型

• app_id：应用ID

• 响应示例：

{ "id": "模板ID", "name": "模板名称", "content": "模板内容", "type": "模板类型", "created_at": "2023-12-25T12:00:00Z" }

12. 更新消息模板

• 接口地址：/console/api/message-templates/<template_id>

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• name：模板名称

• content：模板内容

• type：模板类型

• 响应示例：

{ "id": "模板ID", "name": "模板名称", "content": "模板内容", "type": "模板类型", "created_at": "2023-12-25T12:00:00Z" }

13. 删除消息模板

• 接口地址：/console/api/message-templates/<template_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }Dify 控制台账单接口文档

账单相关接口

1. 获取订阅信息

• 接口地址：/console/api/billing/subscription

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• plan：订阅计划

• interval：订阅周期（monthly, yearly）

• 响应示例：

{ "subscription": { "id": "订阅ID", "plan": "订阅计划", "status": "订阅状态", "interval": "订阅周期", "current_period_start": "2023-12-25T12:00:00Z", "current_period_end": "2024-01-25T12:00:00Z", "cancel_at_period_end": false }, "payment_method": { "type": "支付方式", "last4": "卡号后四位", "exp_month": 12, "exp_year": 2024 } }

2. 创建订阅

• 接口地址：/console/api/billing/subscription

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• plan（必需）：订阅计划

• interval（必需）：订阅周期（monthly, yearly）

• payment_method_id（必需）：支付方式ID

• 响应示例：

{ "subscription": { "id": "订阅ID", "plan": "订阅计划", "status": "订阅状态", "interval": "订阅周期", "current_period_start": "2023-12-25T12:00:00Z", "current_period_end": "2024-01-25T12:00:00Z" } }

3. 更新订阅

• 接口地址：/console/api/billing/subscription

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• plan：订阅计划

• interval：订阅周期（monthly, yearly）

• payment_method_id：支付方式ID

• 响应示例：

{ "subscription": { "id": "订阅ID", "plan": "订阅计划", "status": "订阅状态", "interval": "订阅周期", "current_period_start": "2023-12-25T12:00:00Z", "current_period_end": "2024-01-25T12:00:00Z" } }

4. 取消订阅

• 接口地址：/console/api/billing/subscription/cancel

• 请求方法：POST

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success", "cancel_at": "2024-01-25T12:00:00Z" }

5. 恢复订阅

• 接口地址：/console/api/billing/subscription/resume

• 请求方法：POST

• 认证方式：需要编辑者权限

• 响应示例：

{ "subscription": { "id": "订阅ID", "plan": "订阅计划", "status": "订阅状态", "interval": "订阅周期", "current_period_start": "2023-12-25T12:00:00Z", "current_period_end": "2024-01-25T12:00:00Z" } }

6. 获取发票列表

• 接口地址：/console/api/billing/invoices

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• page：页码（默认1）

• limit：每页数量（默认20）

• status：发票状态

• 响应示例：

{ "data": [ { "id": "发票ID", "number": "发票编号", "amount": 1000, "currency": "USD", "status": "发票状态", "created_at": "2023-12-25T12:00:00Z", "paid_at": "2023-12-25T12:00:00Z" } ], "total": 100, "page": 1, "limit": 20, "has_more": true }

7. 获取发票详情

• 接口地址：/console/api/billing/invoices/<invoice_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "发票ID", "number": "发票编号", "amount": 1000, "currency": "USD", "status": "发票状态", "created_at": "2023-12-25T12:00:00Z", "paid_at": "2023-12-25T12:00:00Z", "lines": [ { "description": "项目描述", "amount": 1000, "currency": "USD", "quantity": 1 } ], "payment_intent": { "id": "支付意向ID", "status": "支付状态", "amount": 1000, "currency": "USD" } }

8. 获取支付方式列表

• 接口地址：/console/api/billing/payment-methods

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "data": [ { "id": "支付方式ID", "type": "支付类型", "last4": "卡号后四位", "exp_month": 12, "exp_year": 2024, "is_default": true } ] }

9. 添加支付方式

• 接口地址：/console/api/billing/payment-methods

• 请求方法：POST

• 认证方式：需要编辑者权限

• 请求参数：

• payment_method_id（必需）：支付方式ID

• is_default：是否设为默认

• 响应示例：

{ "id": "支付方式ID", "type": "支付类型", "last4": "卡号后四位", "exp_month": 12, "exp_year": 2024, "is_default": true }

10. 删除支付方式

• 接口地址：/console/api/billing/payment-methods/<payment_method_id>

• 请求方法：DELETE

• 认证方式：需要编辑者权限

• 响应示例：

{ "result": "success" }

11. 设置默认支付方式

• 接口地址：/console/api/billing/payment-methods/<payment_method_id>/default

• 请求方法：POST

• 认证方式：需要编辑者权限

• 响应示例：

{ "id": "支付方式ID", "type": "支付类型", "last4": "卡号后四位", "exp_month": 12, "exp_year": 2024, "is_default": true }

12. 获取账单设置

• 接口地址：/console/api/billing/settings

• 请求方法：GET

• 认证方式：需要编辑者权限

• 响应示例：

{ "email": "账单邮箱", "name": "账单名称", "address": { "line1": "地址行1", "line2": "地址行2", "city": "城市", "state": "州/省", "postal_code": "邮编", "country": "国家" }, "tax_id": "税号" }

13. 更新账单设置

• 接口地址：/console/api/billing/settings

• 请求方法：PATCH

• 认证方式：需要编辑者权限

• 请求参数：

• email：账单邮箱

• name：账单名称

• address：账单地址

• tax_id：税号

• 响应示例：

{ "result": "success" }Dify 控制台工作区接口文档

工作区管理接口

1. 获取工作区列表

• 接口地址：/console/api/workspaces

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "workspaces": [ { "id": "工作区ID", "name": "工作区名称", "plan": "订阅计划", "status": "工作区状态", "created_at": "2023-12-25T12:00:00Z", "current": true } ] }

2. 获取当前工作区信息

• 接口地址：/console/api/workspaces/current

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "id": "工作区ID", "name": "工作区名称", "plan": "订阅计划", "status": "工作区状态", "created_at": "2023-12-25T12:00:00Z", "role": "用户角色", "in_trial": true, "trial_end_reason": "试用结束原因", "custom_config": {} }

3. 切换工作区

• 接口地址：/console/api/workspaces/switch

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• tenant_id（必需）：目标工作区ID

• 响应示例：

{ "result": "success", "new_tenant": { "id": "工作区ID", "name": "工作区名称", "plan": "订阅计划", "status": "工作区状态" } }

4. 更新工作区自定义配置

• 接口地址：/console/api/workspaces/custom-config

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• remove_webapp_brand：是否移除网页品牌

• replace_webapp_logo：替换网页Logo

• 响应示例：

{ "result": "success", "tenant": { "id": "工作区ID", "name": "工作区名称", "custom_config": { "remove_webapp_brand": true, "replace_webapp_logo": "logo_url" } } }

5. 上传工作区Logo

• 接口地址：/console/api/workspaces/custom-config/webapp-logo/upload

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• file：Logo文件(支持SVG、PNG格式)

• 响应示例：

{ "id": "文件ID" }

工作区成员管理接口

1. 获取成员列表

• 接口地址：/console/api/workspaces/current/members

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success", "accounts": [ { "id": "成员ID", "name": "成员名称", "email": "成员邮箱", "role": "成员角色", "status": "成员状态", "created_at": "2023-12-25T12:00:00Z" } ] }

2. 邀请成员

• 接口地址：/console/api/workspaces/current/members/invite-email

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• emails（必需）：邮箱列表

• role（必需）：角色

• language：界面语言

• 响应示例：

{ "result": "success", "invitation_results": [ { "status": "success", "email": "邮箱地址", "url": "邀请链接" } ] }

3. 取消成员邀请

• 接口地址：/console/api/workspaces/current/members/<member_id>

• 请求方法：DELETE

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success" }

4. 更新成员角色

• 接口地址：/console/api/workspaces/current/members/<member_id>/update-role

• 请求方法：PUT

• 认证方式：需要访问令牌

• 请求参数：

• role（必需）：新角色

• 响应示例：

{ "result": "success" }

5. 获取数据集操作员列表

• 接口地址：/console/api/workspaces/current/dataset-operators

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "result": "success", "accounts": [ { "id": "操作员ID", "name": "操作员名称", "email": "操作员邮箱", "role": "操作员角色", "status": "操作员状态", "created_at": "2023-12-25T12:00:00Z" } ] }

工作区模型管理接口

1. 获取默认模型

• 接口地址：/console/api/workspaces/default-model

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• model_type（必需）：模型类型

• 响应示例：

{ "data": { "provider": "模型提供商", "model": "模型名称", "model_type": "模型类型" } }

2. 设置默认模型

• 接口地址：/console/api/workspaces/default-model

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• model_settings（必需）：模型设置列表

• 响应示例：

{ "result": "success" }

3. 获取提供商模型列表

• 接口地址：/console/api/workspaces/model-providers/<provider>/models

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "data": [ { "model": "模型名称", "model_type": "模型类型", "features": ["特性列表"], "parameters": {} } ] }

4. 配置提供商模型

• 接口地址：/console/api/workspaces/model-providers/<provider>/models

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• credentials：凭证信息

• load_balancing：负载均衡配置

• config_from：配置来源

• 响应示例：

{ "result": "success" }

5. 删除提供商模型

• 接口地址：/console/api/workspaces/model-providers/<provider>/models

• 请求方法：DELETE

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• 响应示例：

{ "result": "success" }

6. 获取模型凭证

• 接口地址：/console/api/workspaces/model-providers/<provider>/model-credentials

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• 响应示例：

{ "credentials": {}, "load_balancing": { "enabled": true, "configs": {} } }

7. 启用模型

• 接口地址：/console/api/workspaces/model-providers/<provider>/models/enable

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• 响应示例：

{ "result": "success" }

8. 禁用模型

• 接口地址：/console/api/workspaces/model-providers/<provider>/models/disable

• 请求方法：PATCH

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• 响应示例：

{ "result": "success" }

9. 验证模型配置

• 接口地址：/console/api/workspaces/model-providers/<provider>/models/validate

• 请求方法：POST

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• credentials：凭证信息

• 响应示例：

{ "result": "success" }

10. 获取模型参数规则

• 接口地址：/console/api/workspaces/model-providers/<provider>/model-parameter-rules

• 请求方法：GET

• 认证方式：需要访问令牌

• 请求参数：

• model（必需）：模型名称

• model_type（必需）：模型类型

• 响应示例：

{ "rules": [ { "parameter": "参数名", "rule": "规则内容" } ] }

11. 获取可用模型列表

• 接口地址：/console/api/workspaces/available-models/<model_type>

• 请求方法：GET

• 认证方式：需要访问令牌

• 响应示例：

{ "data": [ { "provider": "提供商", "model": "模型名称", "model_type": "模型类型", "features": ["特性列表"] } ] }Dify 控制台统计接口文档

统计相关接口

1. 获取应用统计信息

• 接口地址：/console/api/statistics/apps/<app_id>

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_conversations": 1000, "total_messages": 10000, "total_tokens": 100000, "average_response_time": 500, "usage_by_date": [ { "date": "2023-12-25", "conversations": 100, "messages": 1000, "tokens": 10000, "response_time": 500 } ] }

2. 获取应用用户统计

• 接口地址：/console/api/statistics/apps/<app_id>/users

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_users": 1000, "active_users": 500, "new_users": 100, "users_by_date": [ { "date": "2023-12-25", "total": 1000, "active": 500, "new": 100 } ] }

3. 获取应用会话统计

• 接口地址：/console/api/statistics/apps/<app_id>/conversations

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_conversations": 1000, "average_messages_per_conversation": 10, "average_duration": 300, "conversations_by_date": [ { "date": "2023-12-25", "total": 100, "average_messages": 10, "average_duration": 300 } ] }

4. 获取应用消息统计

• 接口地址：/console/api/statistics/apps/<app_id>/messages

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_messages": 10000, "messages_by_role": { "user": 5000, "assistant": 5000 }, "messages_by_date": [ { "date": "2023-12-25", "total": 1000, "user": 500, "assistant": 500 } ] }

5. 获取应用反馈统计

• 接口地址：/console/api/statistics/apps/<app_id>/feedbacks

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_feedbacks": 1000, "positive_rate": 0.8, "feedbacks_by_rating": { "like": 800, "dislike": 200 }, "feedbacks_by_date": [ { "date": "2023-12-25", "total": 100, "like": 80, "dislike": 20 } ] }

6. 获取工作区统计信息

• 接口地址：/console/api/statistics/workspace

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_apps": 10, "total_users": 1000, "total_conversations": 10000, "total_messages": 100000, "total_tokens": 1000000, "storage_usage": 1024, "usage_by_date": [ { "date": "2023-12-25", "apps": 10, "users": 1000, "conversations": 1000, "messages": 10000, "tokens": 100000, "storage": 1024 } ] }

7. 获取工作区成本统计

• 接口地址：/console/api/statistics/workspace/costs

• 请求方法：GET

• 认证方式：需要管理员权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_cost": 1000, "costs_by_type": { "api": 500, "storage": 300, "bandwidth": 200 }, "costs_by_date": [ { "date": "2023-12-25", "total": 100, "api": 50, "storage": 30, "bandwidth": 20 } ] }

8. 获取工作区性能统计

• 接口地址：/console/api/statistics/workspace/performance

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "average_response_time": 500, "error_rate": 0.01, "availability": 0.999, "performance_by_date": [ { "date": "2023-12-25", "response_time": 500, "error_rate": 0.01, "availability": 0.999 } ] }

9. 获取数据集统计信息

• 接口地址：/console/api/statistics/datasets

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_datasets": 10, "total_documents": 1000, "total_segments": 10000, "storage_usage": 1024, "usage_by_date": [ { "date": "2023-12-25", "datasets": 10, "documents": 1000, "segments": 10000, "storage": 1024 } ] }

10. 获取API调用统计

• 接口地址：/console/api/statistics/api-usage

• 请求方法：GET

• 认证方式：需要编辑者权限

• 请求参数：

• start_date：开始日期

• end_date：结束日期

• interval：统计间隔（hour, day, week, month）

• 响应示例：

{ "total_requests": 100000, "requests_by_endpoint": { "/api/chat": 50000, "/api/completion": 30000, "/api/datasets": 20000 }, "requests_by_date": [ { "date": "2023-12-25", "total": 10000, "chat": 5000, "completion": 3000, "datasets": 2000 } ] }Dify 控制台错误码文档

错误码说明

1. 通用错误码

错误码	HTTP状态码	描述	处理建议
400001	400	请求参数错误	检查请求参数是否符合要求
400002	400	请求参数缺失	检查必需的请求参数是否已提供
400003	400	请求参数格式错误	检查参数格式是否正确
400004	400	请求参数值无效	检查参数值是否在有效范围内
401001	401	未认证	检查认证信息是否正确
401002	401	认证失败	检查用户名密码是否正确
401003	401	认证令牌过期	重新获取认证令牌
401004	401	认证令牌无效	使用有效的认证令牌
403001	403	权限不足	检查用户权限是否满足要求
403002	403	访问被拒绝	确认是否有权限访问该资源
403003	403	操作被禁止	确认是否有权限执行该操作
404001	404	资源不存在	检查请求的资源是否存在
404002	404	接口不存在	检查API接口路径是否正确
409001	409	资源冲突	检查是否存在资源冲突
429001	429	请求过于频繁	降低请求频率
500001	500	服务器内部错误	联系技术支持
500002	500	服务暂时不可用	稍后重试
503001	503	服务维护中	等待服务恢复

2. 用户相关错误码

错误码	HTTP状态码	描述	处理建议
400101	400	用户名格式错误	检查用户名格式
400102	400	密码格式错误	检查密码格式
400103	400	邮箱格式错误	检查邮箱格式
401101	401	用户名或密码错误	检查用户名和密码
401102	401	账号已被禁用	联系管理员
403101	403	用户无权限	申请相应权限
404101	404	用户不存在	检查用户ID是否正确
409101	409	用户已存在	使用其他用户名

3. 应用相关错误码

错误码	HTTP状态码	描述	处理建议
400201	400	应用名称无效	检查应用名称格式
400202	400	应用配置无效	检查应用配置参数
403201	403	无应用访问权限	申请应用访问权限
404201	404	应用不存在	检查应用ID是否正确
409201	409	应用名称已存在	使用其他应用名称

4. 数据集相关错误码

错误码	HTTP状态码	描述	处理建议
400301	400	数据集名称无效	检查数据集名称格式
400302	400	数据集配置无效	检查数据集配置参数
403301	403	无数据集访问权限	申请数据集访问权限
404301	404	数据集不存在	检查数据集ID是否正确
409301	409	数据集名称已存在	使用其他数据集名称

5. 文件相关错误码

错误码	HTTP状态码	描述	处理建议
400401	400	文件格式不支持	使用支持的文件格式
400402	400	文件大小超限	压缩文件或分片上传
403401	403	无文件访问权限	申请文件访问权限
404401	404	文件不存在	检查文件ID是否正确
409401	409	文件已存在	使用其他文件名

6. 会话相关错误码

错误码	HTTP状态码	描述	处理建议
400501	400	会话参数无效	检查会话参数
400502	400	会话状态无效	检查会话状态
403501	403	无会话访问权限	申请会话访问权限
404501	404	会话不存在	检查会话ID是否正确
409501	409	会话冲突	等待会话释放

7. 消息相关错误码

错误码	HTTP状态码	描述	处理建议
400601	400	消息内容无效	检查消息内容格式
400602	400	消息长度超限	缩短消息内容
403601	403	无消息访问权限	申请消息访问权限
404601	404	消息不存在	检查消息ID是否正确
409601	409	消息已存在	避免重复发送

8. 账单相关错误码

错误码	HTTP状态码	描述	处理建议
400701	400	支付参数无效	检查支付参数
400702	400	订阅计划无效	选择有效的订阅计划
403701	403	无支付权限	申请支付权限
404701	404	订单不存在	检查订单ID是否正确
409701	409	订单已存在	避免重复下单

9. 工作区相关错误码

错误码	HTTP状态码	描述	处理建议
400801	400	工作区名称无效	检查工作区名称格式
400802	400	工作区配置无效	检查工作区配置参数
403801	403	无工作区访问权限	申请工作区访问权限
404801	404	工作区不存在	检查工作区ID是否正确
409801	409	工作区名称已存在	使用其他工作区名称

10. 统计相关错误码

错误码	HTTP状态码	描述	处理建议
400901	400	统计参数无效	检查统计参数
400902	400	统计时间范围无效	调整统计时间范围
403901	403	无统计访问权限	申请统计访问权限
404901	404	统计数据不存在	检查统计条件是否正确
409901	409	统计任务冲突	等待统计任务完成

Dify 文件服务 API 接口文档

一、接口概述

本文档描述了Dify应用的文件服务API接口，包括图片预览、文件预览、工作区Logo和工具文件等功能。所有接口都遵循RESTful设计规范。

二、接口详情

1. 图片预览接口

1.1 获取图片预览（已废弃）

• 接口地址：/files/{file_id}/image-preview

• 请求方法：GET

• 路径参数：

• file_id：UUID，文件ID

• 查询参数：

• timestamp（必需）：字符串，时间戳

• nonce（必需）：字符串，随机字符串

• sign（必需）：字符串，签名

• 响应头：

• Content-Type：图片MIME类型（如image/jpeg、image/png等）

• 响应示例：

• 返回图片二进制数据流

• 错误响应：

{ "error": { "message": "Invalid request.", "code": 400 } }

2. 文件预览接口

2.1 获取文件预览

• 接口地址：/files/{file_id}/file-preview

• 请求方法：GET

• 路径参数：

• file_id：UUID，文件ID

• 查询参数：

• timestamp（必需）：字符串，时间戳

• nonce（必需）：字符串，随机字符串

• sign（必需）：字符串，签名

• as_attachment（可选）：布尔值，是否作为附件下载，默认false

• 响应头：

• Content-Type：文件MIME类型（如application/pdf、text/plain等）

• Content-Length：文件大小（字节数）

• Content-Disposition：

• 预览模式：不设置

• 下载模式：attachment; filename=原始文件名

• 响应示例：

• 返回文件二进制数据流

• 错误响应：

{ "error": { "message": "Invalid request.", "code": 400 } } { "error": { "message": "File type not allowed.", "code": 415 } }

3. 工作区Logo接口

3.1 获取工作区Logo

• 接口地址：/files/workspaces/{workspace_id}/webapp-logo

• 请求方法：GET

• 路径参数：

• workspace_id：UUID，工作区ID

• 响应头：

• Content-Type：图片MIME类型（如image/jpeg、image/png等）

• Cache-Control：缓存控制策略

• 响应示例：

• 返回Logo图片二进制数据流

• 错误响应：

{ "error": { "message": "webapp logo is not found", "code": 404 } }

4. 工具文件接口

4.1 获取工具文件

• 接口地址：/files/tools/{file_id}.{extension}

• 请求方法：GET

• 路径参数：

• file_id：UUID，文件ID

• extension：字符串，文件扩展名

• 查询参数：

• timestamp（必需）：字符串，时间戳

• nonce（必需）：字符串，随机字符串

• sign（必需）：字符串，签名

• as_attachment（可选）：布尔值，是否作为附件下载，默认false

• 响应头：

• Content-Type：文件MIME类型（根据扩展名确定）

• Content-Length：文件大小（字节数）

• Content-Disposition：

• 预览模式：不设置

• 下载模式：attachment; filename=工具文件名.扩展名

• Cache-Control：缓存控制策略

• 响应示例：

• 返回文件二进制数据流

• 错误响应：

{ "error": { "message": "Invalid request.", "code": 403 } } { "error": { "message": "File type not allowed.", "code": 415 } }

三、状态码说明

• 200 OK：请求成功

• 400 Bad Request：请求参数错误

• 403 Forbidden：请求未授权

• 404 Not Found：文件不存在

• 415 Unsupported Media Type：不支持的文件类型

四、错误处理

所有接口在发生错误时会返回统一格式的错误信息：

{ "error": { "code": "错误代码", "message": "错误描述信息" } }

错误类型

• UnsupportedFileTypeError

• 错误代码：unsupported_file_type

• 状态码：415

• 描述：不支持的文件类型

• 场景：请求预览不支持的文件类型时

五、注意事项

1. 所有文件预览接口都需要进行签名验证

2. 签名验证需要提供timestamp、nonce和sign三个参数

3. 文件下载时可以通过as_attachment参数控制是预览还是下载

4. 图片预览接口已标记为废弃，建议使用文件预览接口

5. 工作区Logo接口需要确保工作区已配置Logo

6. 工具文件预览接口的文件ID和扩展名需要匹配

7. 所有接口的响应都是直接的文件流，需要根据Content-Type正确处理

8. 当文件大小已知时，会在响应头中包含Content-Length

9. 所有图片类型接口支持的MIME类型包括：image/jpeg、image/png、image/gif等

10. 文件预览接口会根据文件扩展名自动设置正确的Content-Type

11. 工具文件接口的扩展名必须与文件的实际类型匹配 Dify 内部 API 接口文档

一、接口概述

本文档描述了Dify应用的内部API接口，包括企业工作区管理等功能。这些接口仅供内部系统调用，不对外开放。所有接口都遵循RESTful设计规范。

二、认证方式

1. 内部API密钥认证

所有内部API请求都需要在HTTP请求头中包含内部API密钥：

X-Inner-Api-Key: your-inner-api-key

认证流程： 1. 检查INNER_API配置是否启用 2. 获取请求头中的X-Inner-Api-Key 3. 验证密钥是否与INNER_API_KEY配置匹配 4. 验证失败时返回401错误

2. 用户认证

某些接口支持用户认证，需要在HTTP请求头中包含用户认证信息：

Authorization: DIFY user-id:signature

认证流程： 1. 检查Authorization请求头 2. 解析user-id和token 3. 生成签名数据：DIFY {user_id} 4. 使用HMAC-SHA1算法和内部API密钥生成签名 5. 将签名进行Base64编码 6. 比对生成的签名与提供的token 7. 验证通过后查询用户信息

签名生成规则： 1. 签名数据格式：DIFY {user_id} 2. 使用HMAC-SHA1算法，以内部API密钥为密钥对签名数据进行签名 3. 将签名结果进行Base64编码

签名生成示例（Python）：

import hmac import base64 from hashlib import sha1 def generate_signature(user_id: str, inner_api_key: str) -> str: data_to_sign = f"DIFY {user_id}" signature = hmac.new( inner_api_key.encode("utf-8"), data_to_sign.encode("utf-8"), sha1 ) return base64.b64encode(signature.digest()).decode("utf-8")

3. 认证规则

• 内部API必须启用（INNER_API配置为true）

• 内部API密钥必须有效

• 用户认证签名必须正确（如果需要用户认证）

三、接口详情

1. 企业工作区接口

1.1 创建企业工作区

• 接口地址：/enterprise/workspace

• 请求方法：POST

• 认证方式：内部API密钥

• 请求头：

• Content-Type: application/json

• X-Inner-Api-Key（必需）：内部API密钥

• 请求参数：

• name（必需）：字符串，工作区名称

• owner_email（必需）：字符串，所有者邮箱

• 请求示例：

{ "name": "企业工作区名称", "owner_email": "owner@example.com" }

• 响应示例：

{ "message": "enterprise workspace created." }

• 错误响应：

{ "message": "owner account not found." }

四、错误处理

所有接口在发生错误时会返回统一格式的错误信息：

{ "message": "错误描述信息" }

错误类型

• Unauthorized

• 状态码：401

• 描述：未提供认证信息或认证信息无效

• 场景：

• 未提供内部API密钥

• 内部API密钥无效

• 用户认证签名无效

• NotFound

• 状态码：404

• 描述：请求的资源不存在

• 场景：

• 内部API未启用

• 所有者账号不存在

错误处理流程

1. 内部API验证

2. 检查INNER_API配置 -> 404 Not Found

3. 验证X-Inner-Api-Key -> 401 Unauthorized

4. 用户认证

5. 解析Authorization头

6. 验证签名

7. 查询用户信息

五、注意事项

1. 内部API密钥应妥善保管，不要泄露给他人

2. 内部API仅供系统内部调用，不要暴露给外部

3. 建议使用HTTPS协议调用API，确保数据传输安全

4. 正确处理API返回的错误信息

5. 在生产环境中建议启用错误监控和日志记录

6. 定期检查内部API密钥的有效性

7. 遵循最小权限原则，仅在必要时启用内部API

8. 用户认证时注意保护签名数据和密钥

9. 建议实现请求频率限制和异常监控 Dify 服务 API 接口文档

一、接口概述

本文档描述了Dify应用的服务API接口，包括应用服务、数据集服务等功能。所有接口都遵循RESTful设计规范。

二、认证方式

1. Bearer Token认证

所有API请求都需要在HTTP请求头中包含Bearer Token：

Authorization: Bearer your-api-token

2. API Token类型

• 应用Token：用于访问应用相关的API

• 数据集Token：用于访问数据集相关的API

3. Token验证规则

• Token必须通过Authorization头传递

• Token必须以"Bearer "为前缀（注意空格）

• Token必须是有效的且未过期

• Token的作用域必须匹配请求的资源类型

三、接口详情

1. 基础接口

1.1 获取API信息

• 接口地址：/

• 请求方法：GET

• 响应示例：

{ "welcome": "Dify OpenAPI", "api_version": "v1", "server_version": "0.3.0" }

2. 应用服务接口

2.1 用户标识

应用服务API支持通过以下方式传递用户标识： - URL查询参数：?user=user-id - JSON请求体：{"user": "user-id"} - 表单数据：user=user-id

如果未提供用户标识，系统将使用默认用户"DEFAULT-USER"。

2.1 获取应用参数

• 接口地址：/parameters

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "opening_statement": "开场白", "suggested_questions": [], "speech_to_text": { "enabled": false }, "text_to_speech": { "enabled": false }, "retriever_resource": { "enabled": false }, "user_input_form": [] }

2.2 获取应用元数据

• 接口地址：/meta

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "app_id": "app-uuid", "name": "应用名称", "mode": "chat", "icon": "应用图标", "icon_background": "图标背景色" }

2.3 获取应用信息

• 接口地址：/info

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "name": "应用名称", "description": "应用描述", "tags": ["标签1", "标签2"] }

2.4 创建补全消息

• 接口地址：/completion-messages

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• user（必需）：用户标识

• inputs（必需）：对象，输入参数

• query（可选）：字符串，查询文本

• files（可选）：数组，文件列表

• response_mode（可选）：字符串，响应模式，可选值：blocking、streaming

• retriever_from（可选）：字符串，检索来源，默认"dev"

• 请求示例：

{ "user": "user-id", "inputs": { "field1": "value1", "field2": "value2" }, "query": "用户问题", "response_mode": "blocking" }

• 响应示例：

{ "answer": "AI回答内容", "message_id": "message-uuid" }

2.5 停止补全

• 接口地址：/completion-messages/{task_id}/stop

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• task_id：字符串，任务ID

• 请求参数：

• user（必需）：用户标识

• 响应示例：

{ "result": "success" }

2.6 发送聊天消息

• 接口地址：/chat-messages

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• user（必需）：用户标识

• inputs（必需）：对象，输入参数

• query（必需）：字符串，聊天内容

• files（可选）：数组，文件列表

• response_mode（可选）：字符串，响应模式，可选值：blocking、streaming

• conversation_id（可选）：UUID，对话ID

• retriever_from（可选）：字符串，检索来源，默认"dev"

• auto_generate_name（可选）：布尔值，是否自动生成对话名称，默认true

• 请求示例：

{ "user": "user-id", "inputs": { "field1": "value1" }, "query": "你好", "response_mode": "streaming", "conversation_id": "conversation-uuid" }

• 响应示例：

{ "answer": "AI回答内容", "conversation_id": "conversation-uuid", "message_id": "message-uuid" }

2.7 停止聊天

• 接口地址：/chat-messages/{task_id}/stop

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• task_id：字符串，任务ID

• 请求参数：

• user（必需）：用户标识

• 响应示例：

{ "result": "success" }

3. 数据集服务接口

3.1 获取数据集列表

• 接口地址：/datasets

• 请求方法：GET

• 认证方式：应用Token

• 请求参数：

• page（可选）：整数，页码，默认1

• limit（可选）：整数，每页数量，默认20

• 响应示例：

{ "data": [ { "id": "dataset-uuid", "name": "数据集名称", "description": "数据集描述", "created_at": "2023-01-01T00:00:00Z" } ], "total": 100, "page": 1, "limit": 20 }

3.2 创建数据集

• 接口地址：/datasets

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• name（必需）：字符串，数据集名称

• description（可选）：字符串，数据集描述

• indexing_technique（可选）：字符串，索引技术

• 请求示例：

{ "name": "我的数据集", "description": "这是一个测试数据集", "indexing_technique": "high_quality" }

• 响应示例：

{ "id": "dataset-uuid", "name": "我的数据集", "description": "这是一个测试数据集", "created_at": "2023-01-01T00:00:00Z" }

3.3 获取数据集详情

• 接口地址：/datasets/{dataset_id}

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 响应示例：

{ "id": "dataset-uuid", "name": "数据集名称", "description": "数据集描述", "documents_count": 10, "word_count": 1000, "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" }

3.4 更新数据集

• 接口地址：/datasets/{dataset_id}

• 请求方法：PUT

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• name（可选）：字符串，数据集名称

• description（可选）：字符串，数据集描述

• 请求示例：

{ "name": "新数据集名称", "description": "新的描述信息" }

• 响应示例：

{ "result": "success" }

3.5 删除数据集

• 接口地址：/datasets/{dataset_id}

• 请求方法：DELETE

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 响应示例：

{ "result": "success" }

3.6 上传文档

• 接口地址：/datasets/{dataset_id}/documents

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: multipart/form-data

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• file（必需）：文件对象

• name（可选）：字符串，文档名称

• process_rule（可选）：对象，处理规则

• 响应示例：

{ "id": "document-uuid", "name": "文档名称", "created_at": "2023-01-01T00:00:00Z" }

3.7 获取文档列表

• 接口地址：/datasets/{dataset_id}/documents

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• page（可选）：整数，页码，默认1

• limit（可选）：整数，每页数量，默认20

• status（可选）：字符串，文档状态

• 响应示例：

{ "data": [ { "id": "document-uuid", "name": "文档名称", "status": "completed", "created_at": "2023-01-01T00:00:00Z" } ], "total": 50, "page": 1, "limit": 20 }

3.8 删除文档

• 接口地址：/datasets/{dataset_id}/documents/{document_id}

• 请求方法：DELETE

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• document_id：UUID，文档ID

• 响应示例：

{ "result": "success" }

3.9 获取数据集分段列表

• 接口地址：/datasets/{dataset_id}/segments

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• keyword（可选）：字符串，搜索关键词

• page（可选）：整数，页码，默认1

• limit（可选）：整数，每页数量，默认20

• 响应示例：

{ "data": [ { "id": "segment-uuid", "content": "分段内容", "document_id": "document-uuid", "position": 1, "word_count": 100, "created_at": "2023-01-01T00:00:00Z" } ], "total": 50, "page": 1, "limit": 20 }

3.10 创建数据集分段

• 接口地址：/datasets/{dataset_id}/segments

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• document_id（必需）：UUID，文档ID

• content（必需）：字符串，分段内容

• position（可选）：整数，分段位置

• 请求示例：

{ "document_id": "document-uuid", "content": "分段内容", "position": 1 }

• 响应示例：

{ "id": "segment-uuid", "created_at": "2023-01-01T00:00:00Z" }

3.11 更新数据集分段

• 接口地址：/datasets/{dataset_id}/segments/{segment_id}

• 请求方法：PUT

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• segment_id：UUID，分段ID

• 请求参数：

• content（必需）：字符串，分段内容

• position（可选）：整数，分段位置

• 请求示例：

{ "content": "新的分段内容", "position": 2 }

• 响应示例：

{ "result": "success" }

3.12 删除数据集分段

• 接口地址：/datasets/{dataset_id}/segments/{segment_id}

• 请求方法：DELETE

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• segment_id：UUID，分段ID

• 响应示例：

{ "result": "success" }

3.13 数据集命中测试

• 接口地址：/datasets/{dataset_id}/hit-testing

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• dataset_id：UUID，数据集ID

• 请求参数：

• query（必需）：字符串，测试查询文本

• top_k（可选）：整数，返回结果数量，默认3

• 请求示例：

{ "query": "测试查询文本", "top_k": 3 }

• 响应示例：

{ "hits": [ { "segment_id": "segment-uuid", "content": "命中的分段内容", "score": 0.95, "document_id": "document-uuid", "document_name": "文档名称" } ] }

4. 音频服务接口

4.1 音频转文本

• 接口地址：/audio-to-text

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: multipart/form-data

• 请求参数：

• file（必需）：音频文件对象

• 响应示例：

{ "text": "转换后的文本内容" }

4.2 文本转音频

• 接口地址：/text-to-audio

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• text（必需）：字符串，要转换的文本

• voice（可选）：字符串，语音类型

• message_id（可选）：UUID，消息ID

• 请求示例：

{ "text": "要转换的文本内容", "voice": "female", "message_id": "message-uuid" }

• 响应示例：

{ "audio_url": "音频文件URL", "audio_type": "audio/mp3" }

4. 计费和限制

4.1 资源限制检查

系统会对以下资源进行限制检查： - 成员数量限制 - 应用数量限制 - 向量空间容量限制 - 文档数量限制

4.2 知识库限制

• Sandbox计划用户无法使用某些高级功能

• 付费计划用户可以使用全部功能

5. 工作流服务接口

5.1 运行工作流

• 接口地址：/workflows/run

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• inputs（必需）：对象，工作流输入参数

• files（可选）：数组，文件列表

• response_mode（可选）：字符串，响应模式，可选值：blocking、streaming

• 请求示例：

{ "inputs": { "field1": "value1", "field2": "value2" }, "response_mode": "blocking" }

• 响应示例：

{ "task_id": "task-uuid", "status": "success", "result": { "output": "工作流执行结果" } }

5.2 停止工作流任务

• 接口地址：/workflows/tasks/{task_id}/stop

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• task_id：字符串，任务ID

• 响应示例：

{ "result": "success" }

6. 消息服务接口

6.1 获取消息列表

• 接口地址：/messages

• 请求方法：GET

• 认证方式：应用Token

• 请求参数：

• conversation_id（必需）：UUID，对话ID

• first_id（可选）：UUID，起始消息ID

• limit（可选）：整数，每页数量，默认20

• user（可选）：字符串，用户标识

• 响应示例：

{ "data": [ { "id": "message-uuid", "conversation_id": "conversation-uuid", "inputs": { "field1": "value1" }, "query": "用户输入", "answer": "AI回答", "feedback": null, "created_at": "2023-01-01T00:00:00Z" } ], "has_more": false }

6.2 消息反馈

• 接口地址：/messages/{message_id}/feedbacks

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• message_id：UUID，消息ID

• 请求参数：

• rating（必需）：字符串，评分，可选值：like、dislike

• user（可选）：字符串，用户标识

• 请求示例：

{ "rating": "like", "user": "user-id" }

• 响应示例：

{ "result": "success" }

6.3 获取相似消息

• 接口地址：/messages/{message_id}/more-like-this

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• message_id：UUID，消息ID

• 请求参数：

• user（可选）：字符串，用户标识

• 响应示例：

{ "data": [ { "id": "message-uuid", "conversation_id": "conversation-uuid", "query": "相似问题", "answer": "AI回答", "created_at": "2023-01-01T00:00:00Z" } ] }

6.4 获取建议问题

• 接口地址：/messages/{message_id}/suggested-questions

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• message_id：UUID，消息ID

• 请求参数：

• user（可选）：字符串，用户标识

• 响应示例：

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

7. 对话服务接口

7.1 获取对话列表

• 接口地址：/conversations

• 请求方法：GET

• 认证方式：应用Token

• 请求参数：

• user（必需）：字符串，用户标识

• first_id（可选）：UUID，起始对话ID

• limit（可选）：整数，每页数量，默认20

• pinned（可选）：布尔值，是否只返回置顶对话

• 响应示例：

{ "data": [ { "id": "conversation-uuid", "name": "对话名称", "inputs": { "field1": "value1" }, "status": "normal", "created_at": "2023-01-01T00:00:00Z", "pinned": false } ], "has_more": false }

7.2 删除对话

• 接口地址：/conversations/{conversation_id}

• 请求方法：DELETE

• 认证方式：应用Token

• 路径参数：

• conversation_id：UUID，对话ID

• 请求参数：

• user（必需）：字符串，用户标识

• 响应示例：

{ "result": "success" }

7.3 重命名对话

• 接口地址：/conversations/{conversation_id}/name

• 请求方法：POST

• 认证方式：应用Token

• 路径参数：

• conversation_id：UUID，对话ID

• 请求参数：

• name（必需）：字符串，新的对话名称

• user（必需）：字符串，用户标识

• 请求示例：

{ "name": "新对话名称", "user": "user-id" }

• 响应示例：

{ "result": "success" }

7.4 置顶对话

• 接口地址：/conversations/{conversation_id}/pin

• 请求方法：PATCH

• 认证方式：应用Token

• 路径参数：

• conversation_id：UUID，对话ID

• 请求参数：

• user（必需）：字符串，用户标识

• 响应示例：

{ "result": "success" }

7.5 取消置顶对话

• 接口地址：/conversations/{conversation_id}/unpin

• 请求方法：PATCH

• 认证方式：应用Token

• 路径参数：

• conversation_id：UUID，对话ID

• 请求参数：

• user（必需）：字符串，用户标识

• 响应示例：

{ "result": "success" }

8. 保存消息服务接口

8.1 获取保存的消息列表

• 接口地址：/saved-messages

• 请求方法：GET

• 认证方式：应用Token

• 请求参数：

• user（必需）：字符串，用户标识

• page（可选）：整数，页码，默认1

• limit（可选）：整数，每页数量，默认20

• 响应示例：

{ "data": [ { "id": "saved-message-uuid", "message_id": "message-uuid", "conversation_id": "conversation-uuid", "query": "用户问题", "answer": "AI回答", "created_at": "2023-01-01T00:00:00Z" } ], "total": 100, "page": 1, "limit": 20 }

8.2 保存消息

• 接口地址：/saved-messages

• 请求方法：POST

• 认证方式：应用Token

• 请求参数：

• message_id（必需）：UUID，消息ID

• user（必需）：字符串，用户标识

• 请求示例：

{ "message_id": "message-uuid", "user": "user-id" }

• 响应示例：

{ "id": "saved-message-uuid", "created_at": "2023-01-01T00:00:00Z" }

8.3 删除保存的消息

• 接口地址：/saved-messages/{message_id}

• 请求方法：DELETE

• 认证方式：应用Token

• 路径参数：

• message_id：UUID，保存的消息ID

• 请求参数：

• user（必需）：字符串，用户标识

• 响应示例：

{ "result": "success" }

9. 站点服务接口

9.1 获取站点信息

• 接口地址：/site

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "title": "站点标题", "description": "站点描述", "icon": "站点图标URL", "icon_background": "#FFFFFF", "default_language": "zh-Hans", "prompt_public": true, "copyright": "版权信息", "privacy_policy": "隐私政策URL", "custom_config": { "theme": "light", "font_family": "Arial" } }

9.2 获取站点配置

• 接口地址：/site/configuration

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "file_upload_limit": 10485760, "supported_file_types": [ "pdf", "doc", "docx", "txt" ], "max_text_length": 10000, "max_conversations": 100, "max_messages_per_conversation": 1000 }

10. 文件服务接口

10.1 获取图片预览

• 接口地址：/files/{file_id}/image-preview

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• file_id：UUID，文件ID

• 响应：

• 返回图片文件流

10.2 获取文件预览

• 接口地址：/files/{file_id}/file-preview

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• file_id：UUID，文件ID

• 请求参数：

• timestamp（必需）：整数，时间戳

• nonce（必需）：字符串，随机字符串

• sign（必需）：字符串，签名

• 响应：

• 返回文件流

10.3 获取工作区Logo

• 接口地址：/files/workspaces/{workspace_id}/webapp-logo

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• workspace_id：UUID，工作区ID

• 响应：

• 返回Logo图片文件流

10.4 获取工具文件预览

• 接口地址：/files/tools/{file_id}.{extension}

• 请求方法：GET

• 认证方式：应用Token

• 路径参数：

• file_id：UUID，文件ID

• extension：字符串，文件扩展名

• 请求参数：

• timestamp（必需）：整数，时间戳

• nonce（必需）：字符串，随机字符串

• sign（必需）：字符串，签名

• 响应：

• 返回文件流

10.5 上传文件

• 接口地址：/files

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: multipart/form-data

• 请求参数：

• file（必需）：文件对象

• type（可选）：字符串，文件类型

• 响应示例：

{ "id": "file-uuid", "name": "文件名", "size": 1024, "type": "image/png", "url": "文件URL", "created_at": "2023-01-01T00:00:00Z" }

11. 远程文件服务接口

11.1 获取远程文件信息

• 接口地址：/remote-files

• 请求方法：GET

• 认证方式：应用Token

• 请求参数：

• url（必需）：字符串，远程文件URL

• 响应示例：

{ "type": "application/pdf", "size": 1024, "name": "文件名.pdf" }

11.2 上传远程文件

• 接口地址：/remote-files

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• Content-Type: application/json

• 请求参数：

• url（必需）：字符串，远程文件URL

• type（可选）：字符串，文件类型

• 请求示例：

{ "url": "https://example.com/file.pdf", "type": "application/pdf" }

• 响应示例：

{ "id": "file-uuid", "name": "文件名", "size": 1024, "type": "application/pdf", "url": "文件URL", "created_at": "2023-01-01T00:00:00Z" }

12. 功能服务接口

12.1 获取系统功能

• 接口地址：/system-features

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "file_upload": { "enabled": true, "max_size": 10485760, "supported_types": [ "pdf", "doc", "docx", "txt" ] }, "speech_to_text": { "enabled": true, "supported_languages": [ "zh-CN", "en-US" ] }, "text_to_speech": { "enabled": true, "supported_voices": [ "female", "male" ] }, "retriever_resource": { "enabled": true, "max_size": 104857600 } }

12.2 获取功能配置

• 接口地址：/features/configuration

• 请求方法：GET

• 认证方式：应用Token

• 响应示例：

{ "max_text_length": 10000, "max_conversations": 100, "max_messages_per_conversation": 1000, "max_saved_messages": 500, "max_file_size": 10485760, "max_audio_size": 5242880, "max_image_size": 5242880 }

13. 认证服务接口

13.1 获取访问令牌

• 接口地址：/passport

• 请求方法：GET

• 认证方式：应用Token

• 请求头：

• X-App-Code（必需）：应用编码

• 响应示例：

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600, "token_type": "Bearer" }

13.2 刷新访问令牌

• 接口地址：/passport/refresh

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• X-App-Code（必需）：应用编码

• 请求参数：

• refresh_token（必需）：字符串，刷新令牌

• 请求示例：

{ "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

• 响应示例：

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600, "token_type": "Bearer" }

13.3 验证访问令牌

• 接口地址：/passport/verify

• 请求方法：POST

• 认证方式：应用Token

• 请求头：

• X-App-Code（必需）：应用编码

• 请求参数：

• access_token（必需）：字符串，访问令牌

• 请求示例：

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

• 响应示例：

{ "valid": true, "expires_in": 1800 }

四、错误处理

所有接口在发生错误时会返回统一格式的错误信息：

{ "error": { "code": "错误代码", "message": "错误描述信息" } }

错误类型

• Unauthorized

• 状态码：401

• 描述：未提供认证信息或认证信息无效

• 场景：

• 未提供Authorization头

• Token格式错误

• Token无效或过期

• Forbidden

• 状态码：403

• 描述：无权访问请求的资源

• 场景：

• 应用API服务已禁用

• 应用状态异常

• 工作空间已归档

• 超出资源使用限制

• 功能仅限付费用户使用

• AppUnavailableError

• 状态码：403

• 描述：应用不可用

• 场景：应用配置错误或功能未启用

• NotChatAppError

• 状态码：400

• 描述：非聊天类型应用

• 场景：对聊天类型应用的API使用了非聊天类型的应用

• ConversationCompletedError

• 状态码：400

• 描述：对话已完成

• 场景：尝试在已完成的对话中发送消息

• ProviderNotInitializeError

• 状态码：400

• 描述：提供商未初始化

• 场景：模型提供商配置错误或未初始化

• ProviderQuotaExceededError

• 状态码：429

• 描述：提供商配额超限

• 场景：超出了模型提供商的使用配额

• ProviderModelCurrentlyNotSupportError

• 状态码：400

• 描述：模型当前不可用

• 场景：所选模型暂时无法使用

• CompletionRequestError

• 状态码：400

• 描述：补全请求错误

• 场景：补全请求参数错误或处理失败

• DatasetNotFoundError

• 状态码：404

• 描述：数据集不存在

• 场景：访问不存在的数据集

• DocumentNotFoundError

• 状态码：404

• 描述：文档不存在

• 场景：访问不存在的文档

• InvalidFileError

• 状态码：400

• 描述：无效的文件

• 场景：上传的文件格式不支持或内容无效

• FileTooLargeError

• 状态码：413

• 描述：文件太大

• 场景：上传的文件超过大小限制

• NoAudioUploadedError

• 状态码：400

• 描述：未上传音频文件

• 场景：音频转文本时未提供音频文件

• AudioTooLargeError

• 状态码：413

• 描述：音频文件太大

• 场景：上传的音频文件超过大小限制

• UnsupportedAudioTypeError

• 状态码：415

• 描述：不支持的音频类型

• 场景：上传了不支持的音频格式

• TextTooLongError

• 状态码：400

• 描述：文本太长

• 场景：要转换的文本超过长度限制

• WorkflowNotFoundError

• 状态码：404

• 描述：工作流不存在

• 场景：访问不存在的工作流

• WorkflowRunError

• 状态码：400

• 描述：工作流运行错误

• 场景：工作流执行过程中发生错误

• TaskNotFoundError

• 状态码：404

• 描述：任务不存在

• 场景：访问不存在的任务

• InvalidInputError

• 状态码：400

• 描述：无效的输入参数

• 场景：工作流输入参数格式错误或缺失必需参数

• MessageNotFoundError

• 状态码：404

• 描述：消息不存在

• 场景：访问不存在的消息

• InvalidFeedbackError

• 状态码：400

• 描述：无效的反馈

• 场景：提供了不支持的反馈类型

• ConversationNotFoundError

• 状态码：404

• 描述：对话不存在

• 场景：访问不存在的对话

• ConversationNameEmptyError

• 状态码：400

• 描述：对话名称为空

• 场景：重命名对话时提供了空名称

• ConversationNameTooLongError

• 状态码：400

• 描述：对话名称太长

• 场景：对话名称超过长度限制

• ConversationCompletedError

• 状态码：400

• 描述：对话已完成

• 场景：尝试修改已完成的对话

• SavedMessageNotFoundError

• 状态码：404

• 描述：保存的消息不存在

• 场景：访问不存在的保存消息

• MessageAlreadySavedError

• 状态码：400

• 描述：消息已保存

• 场景：尝试保存已保存的消息

• SavedMessageLimitExceededError

• 状态码：400

• 描述：保存消息数量超限

• 场景：保存的消息数量超过限制

• SiteNotFoundError

• 状态码：404

• 描述：站点不存在

• 场景：访问不存在的站点

• SiteConfigurationError

• 状态码：400

• 描述：站点配置错误

• 场景：站点配置参数错误或缺失

• FileNotFoundError

• 状态码：404

• 描述：文件不存在

• 场景：访问不存在的文件

• InvalidSignatureError

• 状态码：400

• 描述：无效的签名

• 场景：文件预览请求的签名验证失败

• WorkspaceNotFoundError

• 状态码：404

• 描述：工作区不存在

• 场景：访问不存在的工作区

• UnsupportedFileTypeError

• 状态码：415

• 描述：不支持的文件类型

• 场景：上传了不支持的文件类型

• RemoteFileNotFoundError

• 状态码：404

• 描述：远程文件不存在

• 场景：访问不存在的远程文件

• RemoteFileDownloadError

• 状态码：400

• 描述：远程文件下载失败

• 场景：无法下载远程文件

• InvalidRemoteFileURLError

• 状态码：400

• 描述：无效的远程文件URL

• 场景：提供了无效的远程文件URL

• RemoteFileTooLargeError

• 状态码：413

• 描述：远程文件太大

• 场景：远程文件超过大小限制

• FeatureNotEnabledError

• 状态码：403

• 描述：功能未启用

• 场景：尝试使用未启用的功能

• FeatureConfigurationError

• 状态码：400

• 描述：功能配置错误

• 场景：功能配置参数错误或缺失

• FeatureQuotaExceededError

• 状态码：429

• 描述：功能配额超限

• 场景：超出了功能使用配额

• InvalidAppCodeError

• 状态码：400

• 描述：无效的应用编码

• 场景：提供了无效的应用编码

• InvalidAccessTokenError

• 状态码：401

• 描述：无效的访问令牌

• 场景：提供了无效的访问令牌

• InvalidRefreshTokenError

• 状态码：401

• 描述：无效的刷新令牌

• 场景：提供了无效的刷新令牌

• TokenExpiredError

• 状态码：401

• 描述：令牌已过期

• 场景：使用了过期的令牌

• SegmentNotFoundError

• 状态码：404

• 描述：分段不存在

• 场景：访问不存在的分段

• InvalidSegmentContentError

• 状态码：400

• 描述：无效的分段内容

• 场景：分段内容为空或格式错误

• SegmentPositionConflictError

• 状态码：409

• 描述：分段位置冲突

• 场景：指定的分段位置已被占用

• InvalidQueryError

• 状态码：400

• 描述：无效的查询文本

• 场景：查询文本为空或格式错误

• HitTestingFailedError

• 状态码：500

• 描述：命中测试失败

• 场景：执行命中测试时发生错误 Dify API 接口文档

一、接口概述

本文档描述了Dify应用的Web API接口，包括应用参数获取、对话管理、消息管理、音频处理等功能。所有接口都遵循RESTful设计规范。

二、接口详情

1. 应用相关接口

1.1 获取应用参数

• 接口地址：/parameters

• 请求方法：GET

• 请求参数：无

• 响应示例：

{ "parameters": [ { "name": "parameter_name", "value": "parameter_value" } ] }

1.2 获取应用元数据

• 接口地址：/meta

• 请求方法：GET

• 请求参数：无

• 响应示例：

{ "app_meta": { "name": "应用名称", "description": "应用描述" } }

2. 对话管理接口

2.1 获取对话列表

• 接口地址：/conversations

• 请求方法：GET

• 请求参数：

• last_id（可选）：UUID，上一页最后一条记录的ID

• limit（可选）：整数，每页显示数量，范围1-100，默认20

• pinned（可选）：字符串，"true"或"false"，筛选置顶状态

• sort_by（可选）：字符串，排序方式

• created_at: 创建时间正序

• -created_at: 创建时间倒序

• updated_at: 更新时间正序

• -updated_at: 更新时间倒序（默认）

• 响应示例：

{ "data": [ { "id": "conversation-uuid", "name": "对话名称", "created_at": "2023-12-25T10:00:00Z", "updated_at": "2023-12-25T10:30:00Z" } ], "has_more": true }

2.2 删除对话

• 接口地址：/conversations/{conversation_id}

• 请求方法：DELETE

• 路径参数：

• conversation_id：UUID，要删除的对话ID

• 响应状态码：204

2.3 重命名对话

• 接口地址：/conversations/{conversation_id}/name

• 请求方法：POST

• 路径参数：

• conversation_id：UUID，要重命名的对话ID

• 请求体：

{ "name": "新对话名称", "auto_generate": false }

• 响应示例：

{ "id": "conversation-uuid", "name": "新对话名称" }

2.4 置顶对话

• 接口地址：/conversations/{conversation_id}/pin

• 请求方法：PATCH

• 路径参数：

• conversation_id：UUID，要置顶的对话ID

• 响应示例：

{ "result": "success" }

2.5 取消置顶对话

• 接口地址：/conversations/{conversation_id}/unpin

• 请求方法：PATCH

• 路径参数：

• conversation_id：UUID，要取消置顶的对话ID

• 响应示例：

{ "result": "success" }

3. 消息管理接口

3.1 获取消息列表

• 接口地址：/messages

• 请求方法：GET

• 请求参数：

• conversation_id（必需）：UUID，对话ID

• first_id（可选）：UUID，第一条消息的ID

• limit（可选）：整数，每页显示数量，范围1-100，默认20

• 响应示例：

{ "limit": 20, "has_more": true, "data": [ { "id": "message-uuid", "conversation_id": "conversation-uuid", "parent_message_id": "parent-message-uuid", "inputs": {}, "query": "用户输入", "answer": "AI回答", "message_files": [], "feedback": { "rating": "like" }, "retriever_resources": [], "created_at": "2023-12-25T10:00:00Z", "agent_thoughts": [], "status": "success", "error": null } ] }

3.2 消息反馈

• 接口地址：/messages/{message_id}/feedbacks

• 请求方法：POST

• 路径参数：

• message_id：UUID，消息ID

• 请求体：

{ "rating": "like" // 可选值：like, dislike, null }

• 响应示例：

{ "result": "success" }

3.3 获取相似消息

• 接口地址：/messages/{message_id}/more-like-this

• 请求方法：GET

• 路径参数：

• message_id：UUID，消息ID

• 请求参数：

• response_mode（必需）：字符串，响应模式，可选值：blocking、streaming

• 响应示例：根据response_mode返回不同格式的响应

3.4 获取建议问题

• 接口地址：/messages/{message_id}/suggested-questions

• 请求方法：GET

• 路径参数：

• message_id：UUID，消息ID

• 响应示例：

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

4. 音频处理接口

4.1 语音转文本

• 接口地址：/audio-to-text

• 请求方法：POST

• 请求参数：

• file：音频文件（multipart/form-data）

• 响应示例：

{ "text": "转换后的文本内容" }

4.2 文本转语音

• 接口地址：/text-to-audio

• 请求方法：POST

• 请求体：

{ "message_id": "message-uuid", // 可选 "voice": "voice-id", // 可选，语音ID "text": "要转换的文本", "streaming": false // 可选，是否流式响应 }

• 响应示例：返回音频数据

5. 补全接口

5.1 创建补全消息

• 接口地址：/completion-messages

• 请求方法：POST

• 请求体：

{ "inputs": { "field1": "value1", "field2": "value2" }, "query": "", // 可选 "files": [], // 可选，文件列表 "response_mode": "blocking", // 可选值：blocking、streaming "retriever_from": "web_app" // 可选，默认为web_app }

• 响应示例：根据response_mode返回不同格式的响应

5.2 停止补全

• 接口地址：/completion-messages/{task_id}/stop

• 请求方法：POST

• 路径参数：

• task_id：字符串，任务ID

• 响应示例：

{ "result": "success" }

6. 聊天接口

6.1 发送聊天消息

• 接口地址：/chat-messages

• 请求方法：POST

• 请求体：

{ "inputs": { "field1": "value1", "field2": "value2" }, "query": "用户输入的问题", "files": [], // 可选，文件列表 "response_mode": "blocking", // 可选值：blocking、streaming "conversation_id": "conversation-uuid", // 可选，对话ID "parent_message_id": "message-uuid", // 可选，父消息ID "retriever_from": "web_app" // 可选，默认为web_app }

• 响应示例：根据response_mode返回不同格式的响应

6.2 停止聊天

• 接口地址：/chat-messages/{task_id}/stop

• 请求方法：POST

• 路径参数：

• task_id：字符串，任务ID

• 响应示例：

{ "result": "success" }

7. 文件管理接口

7.1 上传文件

• 接口地址：/files

• 请求方法：POST

• 请求参数：

• file：文件（multipart/form-data）

• source：字符串，可选值：datasets、null，文件来源

• 响应状态码：201

• 响应示例：

{ "id": "file-uuid", "name": "文件名", "size": 1024, "extension": "txt", "mime_type": "text/plain", "created_at": "2023-12-25T10:00:00Z", "url": "文件访问URL" }

8. 保存消息接口

8.1 获取保存的消息列表

• 接口地址：/saved-messages

• 请求方法：GET

• 请求参数：

• last_id（可选）：UUID，上一页最后一条记录的ID

• limit（可选）：整数，每页显示数量，范围1-100，默认20

• 响应示例：

{ "limit": 20, "has_more": true, "data": [ { "id": "message-uuid", "inputs": {}, "query": "用户输入", "answer": "AI回答", "message_files": [], "feedback": { "rating": "like" }, "created_at": "2023-12-25T10:00:00Z" } ] }

8.2 保存消息

• 接口地址：/saved-messages

• 请求方法：POST

• 请求体：

{ "message_id": "message-uuid" }

• 响应示例：

{ "result": "success" }

8.3 删除保存的消息

• 接口地址：/saved-messages/{message_id}

• 请求方法：DELETE

• 路径参数：

• message_id：UUID，消息ID

• 响应示例：

{ "result": "success" }

9. 站点接口

9.1 获取应用站点信息

• 接口地址：/site

• 请求方法：GET

• 响应示例：

{ "app_id": "app-uuid", "end_user_id": "user-uuid", "enable_site": true, "site": { "title": "站点标题", "chat_color_theme": "主题颜色", "chat_color_theme_inverted": false, "icon_type": "图标类型", "icon": "图标", "icon_background": "图标背景色", "icon_url": "图标URL", "description": "站点描述", "copyright": "版权信息", "privacy_policy": "隐私政策", "custom_disclaimer": "自定义免责声明", "default_language": "默认语言", "prompt_public": false, "show_workflow_steps": false, "use_icon_as_answer_icon": false }, "model_config": { "opening_statement": "开场白", "suggested_questions": [], "suggested_questions_after_answer": {}, "more_like_this": {}, "model": {}, "user_input_form": [], "pre_prompt": "预设提示语" }, "plan": "付费计划", "can_replace_logo": true, "custom_config": { "remove_webapp_brand": false, "replace_webapp_logo": "替换的Logo URL" } }

10. 工作流接口

10.1 运行工作流

• 接口地址：/workflows/run

• 请求方法：POST

• 请求体：

{ "inputs": { "field1": "value1", "field2": "value2" }, "files": [] // 可选，文件列表 }

• 响应示例：返回流式响应数据

10.2 停止工作流任务

• 接口地址：/workflows/tasks/{task_id}/stop

• 请求方法：POST

• 路径参数：

• task_id：字符串，任务ID

• 响应示例：

{ "result": "success" }

11. 远程文件接口

11.1 获取远程文件信息

• 接口地址：/remote-files/info/{url}

• 请求方法：GET

• 路径参数：

• url：字符串，经过URL编码的远程文件URL

• 响应示例：

{ "file_type": "application/octet-stream", "file_length": 1024 }

11.2 上传远程文件

• 接口地址：/remote-files/upload

• 请求方法：POST

• 请求体：

{ "url": "远程文件URL" }

• 响应状态码：201

• 响应示例：

{ "id": "file-uuid", "name": "文件名", "size": 1024, "extension": "txt", "url": "文件访问URL", "mime_type": "text/plain", "created_by": "user-uuid", "created_at": "2023-12-25T10:00:00Z" }

12. 系统功能接口

12.1 获取系统功能列表

• 接口地址：/system-features

• 请求方法：GET

• 响应示例：

{ "feature1": true, "feature2": false, "feature3": { "enabled": true, "config": {} } }

13. 认证接口

13.1 获取访问令牌

• 接口地址：/passport

• 请求方法：GET

• 请求头：

• X-App-Code：应用代码，必需

• 响应示例：

{ "access_token": "jwt-token" }

三、状态码说明

• 200 OK：请求成功

• 204 No Content：请求成功，无返回内容

• 400 Bad Request：请求参数错误

• 404 Not Found：请求的资源不存在

• 500 Internal Server Error：服务器内部错误

四、错误处理

所有接口在发生错误时会返回统一格式的错误信息：

{ "error": { "message": "错误描述信息", "code": "错误代码" } }

常见错误类型： - NotChatAppError：非聊天类型应用 - ConversationNotExistsError：对话不存在 - LastConversationNotExistsError：上一页最后一条对话不存在 - AppUnavailableError：应用不可用 - NoAudioUploadedError：未上传音频文件 - AudioTooLargeError：音频文件过大 - UnsupportedAudioTypeError：不支持的音频类型 - ProviderNotSupportSpeechToTextError：提供商不支持语音转文本 - ProviderNotInitializeError：提供商未初始化 - ProviderQuotaExceededError：提供商配额超限 - ProviderModelCurrentlyNotSupportError：提供商模型当前不可用 - CompletionRequestError：请求处理错误 - NotCompletionAppError：非补全类型应用 - ConversationCompletedError：对话已完成 - InvokeRateLimitError：调用频率超限 - NoFileUploadedError：未上传文件 - TooManyFilesError：上传文件数量过多 - FilenameNotExistsError：文件名不存在 - FileTooLargeError：文件过大 - UnsupportedFileTypeError：不支持的文件类型 - NotWorkflowAppError：非工作流类型应用 - RemoteFileUploadError：远程文件上传失败 - WebSSOAuthRequiredError：需要SSO认证 - Unauthorized：未授权访问

五、注意事项

1. 所有接口都需要进行身份认证，具体认证方式请参考认证文档

2. 时间相关字段均使用ISO 8601格式的UTC时间

3. ID字段均使用UUID格式

4. 分页接口使用基于cursor的分页方式，通过last_id参数进行翻页

5. 访问令牌（access_token）需要在每个请求的Authorization头中携带，格式为：Bearer {access_token}