文件上传

适用场景

当你需要先拿到一个可直接上传到对象存储的地址，再把文件上传到 FlowUs 时，使用这个接口。它适合图片、文档、压缩包、音视频和少量通用文件类型的上传流程。

接口信息

这个接口当前要求 pages.write。这和“最终文件会出现在页面内容里”的外部使用场景一致，但不是 blocks.write。

权限要求

需要 pages.write。如果当前 token 没有这个 scope，请求会返回 403 forbidden。

请求参数

请求示例

{
  "filename": "roadmap.pdf",
  "content_type": "application/pdf",
  "content_length": 1048576,
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  }
}

参数说明

请求体当前必须提供 parent.page_id。如果缺少该字段，会返回对应的校验错误。该接口会校验 parent.page_id 对应页面的写权限。

响应结果

{
  "object": "file_upload",
  "id": "upload_15151515-1515-4515-8515-151515151515",
  "upload_url": "https://cos.example.com/upload/roadmap.pdf",
  "oss_name": "oss/15151515-1515-4515-8515-151515151515/roadmap.pdf",
  "file_url": "https://cdn.flowus.cn/oss/15151515-1515-4515-8515-151515151515/roadmap.pdf",
  "expiry_time": "2026-04-09T09:30:00.000Z",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf"
  }
}

拿到响应后，客户端用 PUT 方法把文件内容直接上传到 upload_url，并携带响应里返回的请求头。不要手动设置 Content-Length，应让 HTTP 客户端按实际文件字节数自动计算；只有对象存储返回 2xx 才能认为上传成功。

行为说明或限制

• 单文件最大大小是 100MB，超过会直接返回校验错误。
• 上传地址有效期是 30 分钟，响应里的 expiry_time 就是这个窗口的结束时间。
• 创建文件、图片、音频或视频块时传 oss_name，不要把兼容字段 file_url 当作 external URL 使用。
• MIME 类型是白名单匹配，不会按“只要是某个大类就放行”的方式放宽处理。
• 支持的 MIME 类型按类别看，主要包括：
• 图片：image/jpeg、image/png、image/gif、image/webp、image/svg+xml、image/bmp、image/tiff
• 文档：application/pdf、application/msword、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.ms-excel、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.ms-powerpoint、application/vnd.openxmlformats-officedocument.presentationml.presentation
• 文本：text/plain、text/csv、text/markdown、text/html
• 压缩包：application/zip、application/x-rar-compressed、application/gzip
• 音视频：audio/mpeg、audio/wav、audio/ogg、video/mp4、video/webm、video/quicktime
• 其他：application/json、application/xml、application/octet-stream
• 不在白名单里的 MIME 类型会返回 400 validation_error。

相关文档

前置阅读

• 创建页面
• 追加块子块

下一步

• Markdown 读取

相关参考

• 错误码参考