Upload API

最后更新：2026年7月3日

Upload 是通过上传文件创建的临时资源。它是创建 Media 之前的第一步：上传文件后，响应会返回一个 Upload，再用这个 Upload 的信息来创建 Media。Media 的创建在 CMA（Weegloo User）或 ACMA（Service User）中进行，不在本页范围内。

Upload 是临时资源。创建 24 小时后会过期（expiresAt），若在此之前未转为 Media，它就会消失。Upload 没有发布或版本的概念（没有 version、status、publish 属性），也没有正文字段，只有系统属性 sys。基础 URL 为 https://upload.weegloo.com/v1，所有请求都需要用于认证 Upload 的 Bearer 令牌。

资源结构

下面是把一张服装店商品照片（保温杯图片）上传到某个 Space 后得到的 Upload 响应。它只有 sys，其中包含 owner、expiresAt、size 等键。

{
  "sys": {
    "id": "4bgMfu7cFGYDRQn4jdqFI8tkOWKZIm",
    "type": "Upload",
    "owner": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T04:48:44.057Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T04:48:44.057Z",
    "expiresAt": "2026-06-19T04:48:44.057Z",
    "size": 50847
  }
}

主要键：

  • sys.id：Upload 的唯一标识符。创建 Media 时会传入此值。单条查询与删除路径中的 {uploadId} 也使用它。
  • sys.owner：指向此 Upload 所属位置的引用。targetType 为 Space 或 Organization（参见下方 Space 与 Organization 上下文）。
  • sys.expiresAt：过期时间。为 createdAt 起 24 小时之后，过了这个时间 Upload 就会消失。
  • sys.size：所上传文件的大小（字节）。上例为 50847 字节。

系统属性 (sys)

每个 Upload 都把系统属性放在 sys 对象中。owner、createdBy、updatedBy 以 Refer 形态（{ "sys": { "id", "type": "Refer", "targetType" } }）出现。

属性类型说明
idstring资源唯一标识符。
typestring资源种类。Upload 始终为 "Upload"。
ownerRefer此 Upload 所属位置。targetType 为 Space 或 Organization。
createdByRefer<User>创建该资源的用户。
createdAtstring (date-time)创建时间。
updatedByRefer<User>最后修改该资源的用户。
updatedAtstring (date-time)最后修改时间。
expiresAtstring (date-time)过期时间。为 createdAt 起 24 小时之后，过期后 Upload 会消失。
sizeinteger (int64)所上传文件的大小（字节）。

以上 9 个属性始终包含在响应中。Content 或 Content Type 的 sys 中所带的 version、status、publish 在 Upload 中并不存在。这是因为 Upload 不是用于发布或编号版本的资源，而是创建 Media 的一次性原料。owner 不像其他资源的 space 那样只指向一种类型，而是根据 targetType 指向 Space 或 Organization。

Space 与 Organization 上下文

Upload 可以在两种上下文中创建，路径和 sys.owner 会随上下文而不同。

上下文路径基准sys.owner.sys.targetType用途
Space/spaces/{spaceId}/uploadsSpace像商品照片那样将成为 Media 原料的文件。
Organization/organizations/{organizationId}/uploadsOrganization像组织图标那样的组织级资产。

Space 上下文中的 Upload 是创建该 Space 之 Media 的原料。Organization 上下文中的 Upload 用于上传像组织图标那样直接用于组织的文件。两种情况下响应返回的资源结构相同，只有 sys.owner 的 targetType 值不同。

上传方式：multipart 与 binary

上传文件的 POST 请求有两种方式。无论哪一种，响应返回的都是同一种 Upload 资源。

multipart 方式将请求正文以 multipart/form-data 发送。文件放在名为 file 的表单字段中。它适合像在浏览器的文件选择输入框中直接上传那样、以表单数据发送的场景。

binary 方式将文件的原始字节直接放入请求正文。对正文的媒体类型（Content-Type）没有限制（通常使用 application/octet-stream），在 Space 上下文中必须在 Content-Length 头中一并发送正文的字节长度。它适合无表单结构、只传输文件字节的服务端代码等场景。

API

以下所有端点的基准 URL 均为 https://upload.weegloo.com/v1，并需要在 Authorization 头中提供用于认证 Upload 的 Bearer 令牌。先介绍 Space 上下文的 4 个，再介绍 Organization 上下文的 4 个。

  • Media：用已上传的 Upload 创建 Media 的请求格式。
  • Media（概念）：在内容工作室中处理文件资产的方法。