Skip to main content
post/files/upload
Request example
Response
post/files/upload

Authorization

Authorizationstringheaderrequired#

每个请求都通过 API Key 认证:Authorization: Bearer {API_KEY}。应用接口使用应用 API Key,知识库接口使用知识库 API Key(快速开始)。

API Key 应保存在服务端,切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401(unauthorized)。

Body

multipart/form-data
filefilerequired#

要上传的文件,作为 multipart/form-data 的一个部分。文件名不能包含 / 或 \。

除部署安全黑名单(UPLOAD_FILE_EXTENSION_BLACKLIST,默认为空)中的扩展名外,任何文件类型都可上传。

文件大小按类别限制:图片 10 MB、音频 50 MB、视频 100 MB、其他文件 15 MB(默认值,Dify Cloud 使用默认值)。自部署可通过 UPLOAD_*_FILE_SIZE_LIMIT 环境变量 调整。

userstring#
该上传所属的终端用户标识,由你的应用定义,需在应用内唯一。省略时上传归属于共享的 DEFAULT-USER。只有携带相同 user 的后续请求才能引用该文件。参见 终端用户身份。

Responses

application/json
文件上传成功。
conversation_idstring#
关联的会话 ID。
created_atinteger#
上传时间戳(Unix 纪元秒)。
created_bystring#
上传者的终端用户 ID。可通过 获取终端用户信息 查询详情。
extensionstring#
文件扩展名。
file_keystring#
未使用,始终为 null。
idstring#
唯一文件 ID。
mime_typestring#
文件的 MIME 类型。
namestring#
文件名。
original_urlstring#
文件的原始 URL。
preview_urlstring#
文件的预览 URL。
referencestring#
在 Agent 和工具场景中附加文件时内部使用的不透明文件引用。通过此端点上传的文件始终为 null。
sizeinteger#
文件大小(字节)。
source_urlstring#
文件的签名下载 URL。
tenant_idstring#
关联的租户 ID。
user_idstring#
未使用,始终为 null。