> ## 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. # 上传文件 > **适用于**：Workflow、Chatflow。 上传文件，供当前环境中的该应用在请求里引用。 返回的 `id` 只对携带相同 `user`、指向同一应用和同一环境的请求有效。单次运行最多引用 100 个文件。 **对应的标准 API 接口**：[上传文件](/zh/3.13.x/develop/api/files/upload-file)。差异： - `user` 为必填。 - 响应中的 `source_url` 是带签名的下载 URL。 - 在 `user` 字段之前到达的所有部分，累计大小上限为 100 MiB。 - 错误码不同。 ## OpenAPI ````yaml /zh/3.13.x/develop/api/openapi_service.json post /v2/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: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 - name: 部署环境 description: >- 部署环境通过 `v2` 基础 URL 提供的接口。部署环境只提供本组中的接口，调用其他路径会返回 `404 not_found`。认证方式和错误码与标准服务 API 不同，部署环境以本组页面为准。 paths: /v2/files/upload: post: tags: - 部署环境 summary: 上传文件 description: |- **适用于**：Workflow、Chatflow。 上传文件，供当前环境中的该应用在请求里引用。 返回的 `id` 只对携带相同 `user`、指向同一应用和同一环境的请求有效。单次运行最多引用 100 个文件。 **对应的标准 API 接口**：[上传文件](/zh/3.13.x/develop/api/files/upload-file)。差异： - `user` 为必填。 - 响应中的 `source_url` 是带签名的下载 URL。 - 在 `user` 字段之前到达的所有部分，累计大小上限为 100 MiB。 - 错误码不同。 operationId: uploadDeployedFileCn requestBody: description: 文件上传请求。需要 multipart/form-data 格式。 required: true content: multipart/form-data: schema: type: object required: - file - user properties: file: type: string format: binary description: >- 要上传的文件，作为 `multipart/form-data` 的一个部分。文件名不能包含 `/` 或 `\`。 除部署安全黑名单（`UPLOAD_FILE_EXTENSION_BLACKLIST`，默认为空）中的扩展名外，任何文件类型都可上传。 各类文件的默认大小上限：图片 5 MB（使用 Docker Compose 部署时为 10 MB）、音频 50 MB、视频 100 MB、其他文件 15 MB。平台管理员可通过 `UPLOAD_*_FILE_SIZE_LIMIT` [环境变量](/zh/3.13.x/deploy/advanced-configuration/environment-variables) 调整这些上限。 user: type: string description: >- 终端用户标识，由你的应用定义，需在应用内唯一。文件归属于当前环境中该应用下的这个 `user`。建议将该部分放在 `file` 之前发送；在它之前到达的内容累计上限为 100 MiB。参见 [终端用户身份](/zh/3.13.x/develop/api/guides/end-user-identity)。 maxLength: 512 responses: '201': description: 已保存的文件，其中的 `id` 可在运行中引用。 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://api.example.com/files/appdeploy/a1b2c3d4-5678-90ab-cdef-1234567890ab/content?token=eyJhbGciOiJIUzI1NiJ9.example original_url: null user_id: null tenant_id: 11223344-5566-7788-99aa-bbccddeeff00 conversation_id: null file_key: null '400': description: >- - `invalid_param`：缺少 `user` 表单字段。`message` 为 `user form field is required`。 - `invalid_param`：multipart 表单无法解析。`message` 为 `invalid multipart form`。 - `invalid_param`：`user` 超过 512 字节。`message` 为 `invalid multipart form`。 - `invalid_param`：`user` 为空或只有空白字符。`message` 为 `user is invalid`。 - `invalid_param`：文件名中含有 `/` 或 `\`。`message` 为 `Filename contains invalid characters`。 - `file_extension_blocked`：文件扩展名在该部署的禁用名单中。 - `no_file_uploaded`：缺少 `file` 部分。 - `too_many_files`：发送了多个 `file` 部分。 - `filename_not_exists_error`：`file` 部分没有文件名。 content: application/json: examples: invalid_param: summary: invalid_param value: code: invalid_param message: user form field is required status: 400 invalid_param_multipart: summary: invalid_param（multipart 表单） value: code: invalid_param message: invalid multipart form status: 400 invalid_param_user: summary: invalid_param（user） value: code: invalid_param message: user is invalid status: 400 invalid_param_filename: summary: invalid_param（文件名） value: code: invalid_param message: Filename contains invalid characters status: 400 file_extension_blocked: summary: file_extension_blocked value: code: file_extension_blocked message: File extension '.exe' is not allowed for security reasons status: 400 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. '401': description: |- - `token_invalid`：API 密钥缺失、格式错误或无法识别。 - `unauthorized`：API 密钥已撤销。 content: application/json: examples: token_invalid: summary: token_invalid value: code: token_invalid message: invalid api token status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 '403': description: '`forbidden`：该应用在 **访问点** 中关闭了 API 访问。' content: application/json: examples: forbidden: summary: forbidden value: code: forbidden message: The app's API service has been disabled. status: 403 '404': description: '`file_not_found`：`user` 无法匹配到该应用的终端用户，若持续出现则联系管理员。' content: application/json: examples: file_not_found: summary: file_not_found value: code: file_not_found message: File not found. status: 404 '413': description: |- - `file_too_large`：在 `user` 字段之前到达的内容超过了 100 MiB。 - `file_too_large`：文件超过该扩展名对应的大小上限，消息中会给出具体的字节数。 content: application/json: examples: file_too_large: summary: file_too_large value: status: 413 code: file_too_large message: File size exceeded. file_too_large_platform_limit: summary: file_too_large（平台上限） value: code: file_too_large message: File size exceeded. The limit is 15728640 bytes. status: 413 '503': description: >- - `file_grant_unavailable`：文件上传暂时不可用，稍后重试。 - `deployment_undeployed`、`deployment_not_ready`、`apprunner_not_deployed`、`enterprise_unavailable`：该环境当前无法处理请求，各错误码的说明参见 [执行工作流](/zh/3.13.x/develop/api/deployed-environments/run-workflow)。 content: application/json: examples: file_grant_unavailable: summary: file_grant_unavailable value: code: file_grant_unavailable message: file upload is temporarily unavailable status: 503 deployment_undeployed: summary: deployment_undeployed value: code: deployment_undeployed message: deployment is not deployed status: 503 deployment_not_ready: summary: deployment_not_ready value: code: deployment_not_ready message: deployment is in progress status: 503 apprunner_not_deployed: summary: apprunner_not_deployed value: code: apprunner_not_deployed message: apprunner not deployed for this environment status: 503 enterprise_unavailable: summary: enterprise_unavailable value: code: enterprise_unavailable message: enterprise routing service unavailable status: 503 servers: - url: https://{deployed_api_base_url} description: 所有部署环境共用的基础 URL，即把标准服务 API 地址中的 `/v1` 换成 `/v2`。 variables: deployed_api_base_url: default: api.example.com description: >- 打开应用的 **访问点** 标签页，从任一部署环境的 **后端服务 API** 卡片复制完整 URL，再去掉开头的 `https://` 和末尾的 `/v2`。 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.13.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.13.x/develop/api/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 ````