> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 上传文件 > **适用于**：Chatflow、Workflow、聊天助手、Agent、文本生成应用。 上传文件并返回其 `id`，供后续请求引用。文件归上传它的终端用户所有：只有携带相同 `user` 的请求才能引用该文件。 应用实际能使用哪些文件类型，取决于它的文件上传设置；可通过 [获取应用参数](/zh/3.11.x/develop/api/applications/get-app-parameters) 读取。 ## OpenAPI ````yaml /zh/3.11.x/develop/api/openapi_service.json post /files/upload openapi: 3.0.1 info: title: Dify 服务 API description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 version: 1.0.0 servers: - url: https://{api_base_url} description: Dify 服务 API 的基础 URL。替换为你部署的 API 基础 URL。 variables: api_base_url: default: api.example.com/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - name: 对话消息 description: 与聊天消息和交互相关的操作。 - name: 文件操作 description: 文件上传和预览操作。 - name: 终端用户 description: 终端用户信息相关操作。 - name: 消息反馈 description: 用户反馈操作。 - name: 会话管理 description: 与管理会话相关的操作。 - name: 语音与文字转换 description: 文字转语音和语音转文字操作。 - name: 应用配置 description: 获取应用设置和信息的操作。 - name: 标注管理 description: 与管理标注直接回复相关的操作。 - name: 人工介入 description: 暂停等待人工输入的工作流恢复操作。 - name: 工作流运行 description: 用于执行和管理工作流的操作。 - name: 文本生成消息 description: 文本生成相关操作。 - name: 知识库 description: 用于管理知识库的操作，包括创建、配置和检索。 - name: 文档 description: 用于在知识库中创建、更新和管理文档的操作。 - name: 分段 description: 用于管理分段和子分段的操作。 - name: 元数据 description: 用于管理知识库元数据字段和文档元数据值的操作。 - name: 标签 description: 用于管理知识库标签和标签绑定的操作。 - name: 模型 description: 用于获取可用模型的操作。 - name: 知识流水线 description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 paths: /files/upload: post: tags: - 文件操作 summary: 上传文件 description: >- **适用于**：Chatflow、Workflow、聊天助手、Agent、文本生成应用。 上传文件并返回其 `id`，供后续请求引用。文件归上传它的终端用户所有：只有携带相同 `user` 的请求才能引用该文件。 应用实际能使用哪些文件类型，取决于它的文件上传设置；可通过 [获取应用参数](/zh/3.11.x/develop/api/applications/get-app-parameters) 读取。 operationId: uploadBasicChatFileCn requestBody: description: 文件上传请求。需要 multipart/form-data 格式。 required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: >- 要上传的文件，作为 `multipart/form-data` 的一个部分。文件名不能包含 `/` 或 `\`。 除部署安全黑名单（`UPLOAD_FILE_EXTENSION_BLACKLIST`，默认为空）中的扩展名外，任何文件类型都可上传。 文件大小按类别限制：图片 10 MB、音频 50 MB、视频 100 MB、其他文件 15 MB（默认值），可通过 `UPLOAD_*_FILE_SIZE_LIMIT` [环境变量](/zh/3.11.x/deploy/advanced-configuration/environment-variables) 调整。 user: type: string description: >- 该上传所属的终端用户标识，由你的应用定义，需在应用内唯一。省略时上传归属于共享的 `DEFAULT-USER`。只有携带相同 `user` 的后续请求才能引用该文件。参见 [终端用户身份](/zh/3.11.x/develop/api/guides/end-user-identity)。 responses: '201': description: 文件上传成功。 content: application/json: schema: $ref: '#/components/schemas/FileUploadResponse' examples: uploadSuccess: summary: 响应示例 value: id: a1b2c3d4-5678-90ab-cdef-1234567890ab reference: null name: product-photo.png size: 204800 extension: png mime_type: image/png created_by: f1e2d3c4-b5a6-7890-abcd-ef1234567890 created_at: 1705407629 preview_url: null source_url: >- https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI= original_url: null user_id: null tenant_id: 11223344-5566-7788-99aa-bbccddeeff00 conversation_id: null file_key: null '400': description: |- - `no_file_uploaded` : 请求中未提供文件。 - `too_many_files` : 每次请求仅允许上传一个文件。 - `filename_not_exists_error` : 上传的文件没有文件名。 - `invalid_param` : 文件名包含 `/` 或 `\`，或文件扩展名在部署的黑名单中。 content: application/json: examples: no_file_uploaded: summary: no_file_uploaded value: status: 400 code: no_file_uploaded message: Please upload your file. too_many_files: summary: too_many_files value: status: 400 code: too_many_files message: Only one file is allowed. filename_not_exists_error: summary: filename_not_exists_error value: status: 400 code: filename_not_exists_error message: The specified filename does not exist. invalid_param: summary: invalid_param value: status: 400 code: invalid_param message: File extension '.exe' is not allowed for security reasons '413': description: >- `file_too_large` : 文件超过其类别的大小限制（见 `file` 字段）。目前运行时返回的 `message` 为空字符串（已知的后端问题），请以 `code` 和状态码为准。 content: application/json: examples: file_too_large: summary: file_too_large value: status: 413 code: file_too_large message: '' '415': description: '`unsupported_file_type` : 上传的 `file` 部分未声明 MIME 类型。' content: application/json: examples: unsupported_file_type: summary: unsupported_file_type value: status: 415 code: unsupported_file_type message: File type not allowed. x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url 'https://{api_base_url}/files/upload' \ --header 'Authorization: Bearer {api_key}' \ --form 'file=@product-photo.png' \ --form 'user={user}' components: schemas: FileUploadResponse: type: object properties: id: type: string format: uuid description: 唯一文件 ID。 reference: type: string nullable: true description: 在 Agent 和工具场景中附加文件时内部使用的不透明文件引用。通过此端点上传的文件始终为 `null`。 name: type: string description: 文件名。 size: type: integer description: 文件大小（字节）。 extension: type: string nullable: true description: 文件扩展名。 mime_type: type: string nullable: true description: 文件的 MIME 类型。 created_by: type: string format: uuid nullable: true description: >- 上传者的终端用户 ID。可通过 [获取终端用户信息](/zh/3.11.x/develop/api/end-users/get-end-user-info) 查询详情。 created_at: type: integer format: int64 description: 上传时间戳（Unix 纪元秒）。 preview_url: type: string nullable: true description: 文件的预览 URL。 source_url: type: string description: 文件的签名下载 URL。 original_url: type: string nullable: true description: 文件的原始 URL。 user_id: type: string format: uuid nullable: true description: 未使用，始终为 `null`。 tenant_id: type: string format: uuid nullable: true description: 关联的租户 ID。 conversation_id: type: string format: uuid nullable: true description: 关联的会话 ID。 file_key: type: string nullable: true description: 未使用，始终为 `null`。 securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/3.11.x/develop/api/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 ````