文件上传 API

Clouisle 提供知识库文档、聊天附件、沙箱产物和文件解析接口。上传与解析请求使用 multipart/form-data，读取文件返回二进制内容；除读取文件外，响应遵循统一的 code、data、msg 结构。

端点总览

支持的格式与大小

知识库文档上传支持 PDF、DOC/DOCX、TXT/Markdown、HTML、CSV、XLS/XLSX、JSON 和 PPTX。图片、压缩包和视频不属于知识库文档类型。

通用图片上传支持 JPEG、PNG、GIF、WebP、SVG 和 ICO；通用文件上传还支持 PDF、TXT、Markdown、HTML、CSV、JSON、DOC/DOCX、XLSX 和 PPTX。

聊天通用上传没有按格式拆分的大小上限；服务端统一执行每文件 10 MB 限制。

上传图片或通用文件

curl -X POST "$API_BASE_URL/api/v1/upload/file" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/report.pdf"

/upload/image 与 /upload/file 都接受 category 查询参数，默认 general，常用值还有 avatar、icon；它决定存储目录并出现在返回的 url 中：

curl -X POST "$API_BASE_URL/api/v1/upload/image?category=avatar" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/avatar.png"

响应中的文件名是生成的存储名。提交聊天附件时，使用响应返回的 url、filename、size 和 mime_type，不要根据 asset_id 自行拼接 /upload/files/{asset_id}。

{
  "code": 0,
  "data": {
    "asset_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "/api/v1/upload/files/general/2026/09/7f3a1c9d2b10_a1b2c3d4.pdf",
    "filename": "7f3a1c9d2b10_a1b2c3d4.pdf",
    "original_name": "report.pdf",
    "size": 1048576,
    "content_type": "application/pdf"
  },
  "msg": "success"
}

将元数据放入 Agent 聊天请求的 file_urls 数组；已解析文件的旧 files 字段已弃用。详见 Agent 聊天 API。

解析文件

curl -X POST "$API_BASE_URL/api/v1/upload/parse?max_content_length=100000&truncate_strategy=end" \
  -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  -F "file=@/path/to/document.pdf"

max_content_length 默认 100000，允许 1000–500000；truncate_strategy 支持 end、start 和 middle。批量解析使用字段名 files，每次最多 5 个文件；单个文件失败会记录在对应错误结果中。

知识库文档与沙箱产物

知识库文档上传成功后状态为 pending。配置分块参数后，调用知识库处理端点开始嵌入和索引。

沙箱产物端点可以使用 JWT 或 clou_ API Key；内部沙箱请求也可以改用签名：请求头 X-Sandbox-Artifact-Timestamp（Unix 秒）与 X-Sandbox-Artifact-Signature，时间戳与当前时间相差超过 300 秒即被拒绝。大小限制由站点设置 SANDBOX_ARTIFACT_MAX_FILE_SIZE_MB 控制。

读取与删除文件

GET /api/v1/upload/files/{category}/{year}/{month}/{filename}

返回存储文件的二进制内容。上传响应里的 url 已经是这个路径，直接使用即可；category、year、month、filename 会做路径段校验，不能包含 .. 或分隔符。

• 普通分类（如 general、avatar、icon）可直接读取，不需要认证头。
• 受保护分类（agent-attachments、sandbox-artifacts、generated-images、generated-videos）以及任何挂着作用域引用的资产，必须带当前 JWT 或 clou_ API Key；缺失返回 401，无权访问返回 403，资产不存在或已不可用返回 404。

curl -H "Authorization: Bearer $CLOUISLE_TOKEN" \
  "$API_BASE_URL/api/v1/upload/files/generated-images/2026/09/9a8b7c6d5e4f_55667788.png" \
  --output image.png

DELETE /api/v1/upload/files/{category}/{year}/{month}/{filename}

删除存储文件，仅超级管理员可用；成功后 data 为 null。

访问控制与预览状态

受保护资产包括聊天附件（agent-attachments）、沙箱产物（sandbox-artifacts）、生成图片（generated-images）与生成视频（generated-videos）。读取或下载它们时，服务端按资产所属的执行作用域授权，作用域只有两种：

• conversation：校验调用者能否访问该会话；API Key 还必须对会话所属 Agent 有权限。
• workflow_run：校验调用者能否访问该工作流运行（触发者、工作流可见性）；API Key 还必须对工作流有权限。

资产没有任何作用域引用时，只有创建者本人或超级管理员可读。授权在读取字节之前完成，不会先落盘再判权。

聊天中生成的图片与视频在生成后注册为 Asset 并挂到对应消息的资产列表（会话作用域），因此刷新页面或重开历史仍能取回；沙箱产物同样以资产形式登记并跟随工作流运行作用域。

• 受保护媒体 URL 必须携带当前 JWT 或 API Key。客户端应展示未认证、无权限、不可用和预览过大状态，不得回退到未认证原始 URL。
• asset_ref 仅在对应会话或工作流运行范围内有效，不要猜测或跨范围复用；换作用域后同一 asset_ref 不再解析。

预览与展示应显式区分以下状态，而不是统一显示「加载失败」：

错误

上传或解析失败时读取响应中的 data.errors 和 msg，不要仅依据 HTTP 状态码判断失败原因。