SuperSplat API 参考

使用此 API 上传高斯泼溅场景，并列出已认证用户拥有的场景。

典型上传流程：

指定源格式及可选展示元数据，创建可恢复的上传会话。
为待上传分片编号请求签名 URL，再通过 PUT 向这些地址上传字节。
提交已上传分片的 ETag 完成上传。泼溅立即创建，处理完成前可能保持 processing 状态。

身份认证与服务地址

在请求头中提供 Authorization: Bearer <API_TOKEN>。请使用有权访问目标账户及场景的 API 令牌。

https://playcanvas.com/api/supersplat

账户

调用者身份。

获取已认证调用者

GET /v1/me

返回已认证调用者的身份。

响应

200 已认证调用者

application/json对象

已认证调用者身份。

属性	要求	类型与说明
`id`	必填	字符串已认证用户 ID。字段示例 `[ "123" ]`
`username`	可选	字符串 / 空值用户名，若可用。可选结构 1 字符串可选结构 2 空值字段示例 `[ "artist" ]`

已认证调用者

{
  "id": "123",
  "username": "artist"
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

泼溅

列出和查看已认证用户拥有的泼溅。

列出已认证调用者拥有的泼溅

GET /v1/splats

返回已认证用户拥有的泼溅分页列表。响应使用 visibility，此 API 不提供单独的 listed 布尔值。

请求参数

名称位置要求说明

名称	位置	要求	说明
`limit`	查询	可选	最多返回的泼溅数量。整数最多返回的泼溅数量。最小值：`1` 最大值：`128` 默认值：`50` 字段示例 `[ 50 ]`
`skip`	查询	可选	跳过的泼溅数量。整数跳过的泼溅数量。最小值：`0` 最大值：`100000` 默认值：`0` 字段示例 `[ 0 ]`

limit

查询

可选

最多返回的泼溅数量。

整数

最多返回的泼溅数量。

最小值：1

最大值：128

默认值：50

字段示例

[
  50
]

skip

查询

可选

跳过的泼溅数量。

整数

跳过的泼溅数量。

最小值：0

最大值：100000

默认值：0

字段示例

[
  0
]

响应

200 调用者的泼溅

application/json对象

泼溅分页列表。

属性要求类型与说明

data

必填

数组

已认证用户拥有的泼溅。

数组项目结构

对象

已认证用户拥有的泼溅场景。

属性	要求	类型与说明
`id`	必填	字符串公开的 8 字符泼溅 ID。字段示例 `[ "a1b2c3d4" ]`
`title`	必填	字符串展示标题。字段示例 `[ "garden-scan" ]`
`description`	必填	字符串展示描述。字段示例 `[ "" ]`
`status`	必填	字符串泼溅发布生命周期状态。可选值：`"processing"` `"completed"` `"failed"` 字段示例 `[ "processing" ]`
`visibility`	必填	字符串泼溅是否公开列出，或仅能通过直接链接访问。可选值：`"listed"` `"unlisted"` 字段示例 `[ "unlisted" ]`
`format`	必填	字符串 / 空值处理完成后的发布输出格式，处理中为 `null`。可选结构 1 字符串可选结构 2 空值字段示例 `[ null ]`
`size`	必填	整数发布泼溅的字节大小。处理中且尚无输出时可能为 `0`。最小值：`0` 最大值：`25000000000` 字段示例 `[ 0 ]`
`viewerUrl`	必填	字符串查看泼溅的 URL。字段示例 `[ "https://superspl.at/scene/a1b2c3d4" ]`
`createdAt`	必填	字符串 / 空值创建时间戳。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ "2026-01-01T00:00:00.000Z" ]`
`updatedAt`	必填	字符串 / 空值最后更新时间戳。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ "2026-01-01T00:00:00.000Z" ]`
`completedAt`	必填	字符串 / 空值处理完成时间戳，处理中为 `null`。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ null ]`

pagination

必填

对象

属性要求类型与说明

skip

必填

整数

已跳过的泼溅数量。

最小值：0

最大值：100000

limit

必填

整数

请求的泼溅最大数量。

最小值：1

最大值：128

total

必填

整数

调用者拥有且匹配条件的泼溅总数。

最小值：0

最大值：100000000

拥有的泼溅

{
  "data": [
    {
      "id": "a1b2c3d4",
      "title": "garden-scan",
      "description": "",
      "status": "processing",
      "visibility": "unlisted",
      "format": null,
      "size": 0,
      "viewerUrl": "https://superspl.at/scene/a1b2c3d4",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": null
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 50,
    "total": 1
  }
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

获取已认证调用者拥有的单个泼溅

GET /v1/splats/{splatId}

返回已认证用户拥有的单个泼溅。刚完成上传时可能返回 status: "processing"，直到处理完成。

请求参数

名称位置要求说明

名称	位置	要求	说明
`splatId`	路径	必填	不透明的公开泼溅 ID。字符串不透明的公开泼溅 ID。最短长度：`1` 最长长度：`100` 字段示例 `[ "a1b2c3d4" ]`

splatId

路径

必填

不透明的公开泼溅 ID。

字符串

不透明的公开泼溅 ID。

最短长度：1

最长长度：100

字段示例

[
  "a1b2c3d4"
]

响应

200 泼溅

application/json对象

已认证用户拥有的泼溅场景。

属性	要求	类型与说明
`id`	必填	字符串公开的 8 字符泼溅 ID。字段示例 `[ "a1b2c3d4" ]`
`title`	必填	字符串展示标题。字段示例 `[ "garden-scan" ]`
`description`	必填	字符串展示描述。字段示例 `[ "" ]`
`status`	必填	字符串泼溅发布生命周期状态。可选值：`"processing"` `"completed"` `"failed"` 字段示例 `[ "processing" ]`
`visibility`	必填	字符串泼溅是否公开列出，或仅能通过直接链接访问。可选值：`"listed"` `"unlisted"` 字段示例 `[ "unlisted" ]`
`format`	必填	字符串 / 空值处理完成后的发布输出格式，处理中为 `null`。可选结构 1 字符串可选结构 2 空值字段示例 `[ null ]`
`size`	必填	整数发布泼溅的字节大小。处理中且尚无输出时可能为 `0`。最小值：`0` 最大值：`25000000000` 字段示例 `[ 0 ]`
`viewerUrl`	必填	字符串查看泼溅的 URL。字段示例 `[ "https://superspl.at/scene/a1b2c3d4" ]`
`createdAt`	必填	字符串 / 空值创建时间戳。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ "2026-01-01T00:00:00.000Z" ]`
`updatedAt`	必填	字符串 / 空值最后更新时间戳。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ "2026-01-01T00:00:00.000Z" ]`
`completedAt`	必填	字符串 / 空值处理完成时间戳，处理中为 `null`。可选结构 1 字符串格式规则：`"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"` 可选结构 2 空值字段示例 `[ null ]`

处理中的泼溅

{
  "id": "a1b2c3d4",
  "title": "garden-scan",
  "description": "",
  "status": "processing",
  "visibility": "unlisted",
  "format": null,
  "size": 0,
  "viewerUrl": "https://superspl.at/scene/a1b2c3d4",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": null
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

404 未找到

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

未找到资源

{
  "error": "Resource not found"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

上传

创建并完成可恢复的泼溅上传。

创建可恢复的泼溅上传

POST /v1/splats/uploads

启动分片上传并返回可恢复上传会话。title 可选，省略时由 PlayCanvas 分配默认标题。新泼溅默认不公开列出。使用 softwareTools 为新泼溅明确标注软件目录 ID。

请求参数

名称位置要求说明

名称	位置	要求	说明
`Idempotency-Key`	请求头	可选	安全重试创建上传请求的可选键。重复使用同一键会返回已有上传会话。字符串安全重试创建上传请求的可选键。重复使用同一键会返回已有上传会话。最短长度：`1` 最长长度：`200` 字段示例 `[ "upload-garden-scan-2026-01-01" ]`

Idempotency-Key

请求头

可选

安全重试创建上传请求的可选键。重复使用同一键会返回已有上传会话。

字符串

安全重试创建上传请求的可选键。重复使用同一键会返回已有上传会话。

最短长度：1

最长长度：200

字段示例

[
  "upload-garden-scan-2026-01-01"
]

请求体（必填）

application/json对象

创建可恢复泼溅上传会话的请求体。

不允许额外属性。

属性要求类型与说明

contentLength

可选

整数 / 空值

源文件总字节数。可选但强烈推荐提供，以便 PlayCanvas 在 S3 分片上传开始前拒绝超限文件。

可选结构 1

整数

最小值：0

最大值：25000000000

可选结构 2

空值

字段示例

[
  125829120
]

sourceFormat

必填

字符串

上传文件格式。原始高斯泼溅 PLY 文件使用 ply，SOG 文件使用 sog，SuperSplat 导出的 SSOG 归档使用 ssog，LCC 归档使用 lcc。

可选值："ply" "sog" "ssog" "lcc"

字段示例

[
  "ply"
]

title

可选

字符串

可选泼溅展示标题，省略时 PlayCanvas 分配默认标题。

最短长度：1

最长长度：100

字段示例

[
  "Garden scan"
]

description

可选

字符串

可选泼溅展示描述。

最长长度：5000

字段示例

[
  "Back garden scan captured at dusk."
]

uploadClient

可选

对象

随上传记录的客户端应用信息。

不允许额外属性。

属性要求类型与说明

id

必填

字符串

创建上传的应用或集成的稳定小写标识符，例如 lcc-studio。

最短长度：1

最长长度：64

格式规则："^[a-z0-9][a-z0-9-]{0,63}$"

字段示例

[
  "lcc-studio"
]

version

可选

字符串

上传客户端应用的可选版本。

最短长度：1

最长长度：64

字段示例

[
  "1.2.3"
]

softwareTools

可选

数组

为新泼溅署名的可选软件目录 ID。通过软件目录端点获取当前支持的 ID；由于目录可能扩展，此字段不是 OpenAPI 枚举。

最多项目：6

数组项目不得重复。

数组项目结构

字符串

软件目录 ID。

最短长度：1

最长长度：64

格式规则："^[a-z0-9][a-z0-9-]{0,63}$"

字段示例

[
  "lcc-studio"
]

字段示例

[
  [
    "lcc-studio"
  ]
]

推荐的 PLY 上传

已知文件大小时创建上传会话。

{
  "sourceFormat": "ply",
  "contentLength": 125829120,
  "title": "Garden scan"
}

最简 PLY 上传

创建时无法获知文件大小，可省略 contentLength。

{
  "sourceFormat": "ply"
}

携带客户端元数据的上传

{
  "sourceFormat": "ply",
  "contentLength": 125829120,
  "title": "Garden scan",
  "uploadClient": {
    "id": "lcc-studio",
    "version": "1.2.3"
  }
}

携带软件署名的上传

{
  "sourceFormat": "ply",
  "contentLength": 125829120,
  "title": "Garden scan",
  "uploadClient": {
    "id": "lcc-studio",
    "version": "1.2.3"
  },
  "softwareTools": [
    "lcc-studio"
  ]
}

响应

200 幂等键对应的已有上传会话

application/json对象

可恢复上传会话状态。

属性要求类型与说明

id

必填

字符串

可恢复上传会话 ID。

字段示例

[
  "upl_0123456789abcdef01234567"
]

status

必填

字符串

可恢复上传会话生命周期状态。processing 表示字节已提交，正在完成泼溅处理。

可选值："created" "uploading" "processing" "completed" "canceled"

字段示例

[
  "created"
]

contentLength

必填

整数 / 空值

创建上传时声明的源文件总字节数，客户端未提供时为 null。

可选结构 1

整数

最小值：0

最大值：25000000000

可选结构 2

空值

字段示例

[
  null
]

sourceFormat

必填

字符串

上传文件格式。原始高斯泼溅 PLY 文件使用 ply，SOG 文件使用 sog，SuperSplat 导出的 SSOG 归档使用 ssog，LCC 归档使用 lcc。

可选值："ply" "sog" "ssog" "lcc"

字段示例

[
  "ply"
]

title

必填

字符串

新泼溅将使用的展示标题。

字段示例

[
  "garden-scan"
]

description

必填

字符串

新泼溅将使用的展示描述。

字段示例

[
  ""
]

softwareTools

可选

数组

为新泼溅署名的可选软件目录 ID。通过软件目录端点获取当前支持的 ID；由于目录可能扩展，此字段不是 OpenAPI 枚举。

最多项目：6

数组项目不得重复。

数组项目结构

字符串

软件目录 ID。

最短长度：1

最长长度：64

格式规则："^[a-z0-9][a-z0-9-]{0,63}$"

字段示例

[
  "lcc-studio"
]

字段示例

[
  [
    "lcc-studio"
  ]
]

partSize

必填

整数

服务器选定的每分片目标字节数，用于拆分文件的分片范围，最后一个分片可更小。

最小值：1

最大值：25000000000

字段示例

[
  67108864
]

uploadedParts

必填

数组

服务器已检测到的分片，用于恢复中断的上传。

数组项目结构

对象

属性要求类型与说明

partNumber

必填

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

etag

必填

字符串

已上传分片的 ETag。

字段示例

[
  "\"abc123\""
]

size

可选

整数

实际检测到的此分片字节数，若已知。这是恢复元数据，并非目标分片尺寸。

最小值：0

最大值：25000000000

字段示例

[
  67108864
]

expiresAt

必填

字符串

上传会话过期时间。

格式规则："^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"

字段示例

[
  "2026-01-01T00:00:00.000Z"
]

已有上传会话

{
  "id": "upl_0123456789abcdef01234567",
  "status": "created",
  "contentLength": 125829120,
  "sourceFormat": "ply",
  "title": "Garden scan",
  "description": "",
  "partSize": 67108864,
  "uploadedParts": [],
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

201 上传会话已创建

application/json对象

可恢复上传会话状态。

属性要求类型与说明

id

必填

字符串

可恢复上传会话 ID。

字段示例

[
  "upl_0123456789abcdef01234567"
]

status

必填

字符串

可恢复上传会话生命周期状态。processing 表示字节已提交，正在完成泼溅处理。

可选值："created" "uploading" "processing" "completed" "canceled"

字段示例

[
  "created"
]

contentLength

必填

整数 / 空值

创建上传时声明的源文件总字节数，客户端未提供时为 null。

可选结构 1

整数

最小值：0

最大值：25000000000

可选结构 2

空值

字段示例

[
  null
]

sourceFormat

必填

字符串

上传文件格式。原始高斯泼溅 PLY 文件使用 ply，SOG 文件使用 sog，SuperSplat 导出的 SSOG 归档使用 ssog，LCC 归档使用 lcc。

可选值："ply" "sog" "ssog" "lcc"

字段示例

[
  "ply"
]

title

必填

字符串

新泼溅将使用的展示标题。

字段示例

[
  "garden-scan"
]

description

必填

字符串

新泼溅将使用的展示描述。

字段示例

[
  ""
]

softwareTools

可选

数组

为新泼溅署名的可选软件目录 ID。通过软件目录端点获取当前支持的 ID；由于目录可能扩展，此字段不是 OpenAPI 枚举。

最多项目：6

数组项目不得重复。

数组项目结构

字符串

软件目录 ID。

最短长度：1

最长长度：64

格式规则："^[a-z0-9][a-z0-9-]{0,63}$"

字段示例

[
  "lcc-studio"
]

字段示例

[
  [
    "lcc-studio"
  ]
]

partSize

必填

整数

服务器选定的每分片目标字节数，用于拆分文件的分片范围，最后一个分片可更小。

最小值：1

最大值：25000000000

字段示例

[
  67108864
]

uploadedParts

必填

数组

服务器已检测到的分片，用于恢复中断的上传。

数组项目结构

对象

属性要求类型与说明

partNumber

必填

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

etag

必填

字符串

已上传分片的 ETag。

字段示例

[
  "\"abc123\""
]

size

可选

整数

实际检测到的此分片字节数，若已知。这是恢复元数据，并非目标分片尺寸。

最小值：0

最大值：25000000000

字段示例

[
  67108864
]

expiresAt

必填

字符串

上传会话过期时间。

字段示例

[
  "2026-01-01T00:00:00.000Z"
]

已创建的上传会话

{
  "id": "upl_0123456789abcdef01234567",
  "status": "created",
  "contentLength": 125829120,
  "sourceFormat": "ply",
  "title": "Garden scan",
  "description": "",
  "partSize": 67108864,
  "uploadedParts": [],
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

400 请求错误

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

无效请求

{
  "error": "Invalid request"
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

413 超过上传限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

上传内容过大

{
  "error": "Upload size limit exceeded"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

获取可恢复上传会话

GET /v1/splats/uploads/{uploadId}

返回上传会话状态及服务器已检测到的分片，用于恢复中断的上传。

请求参数

名称位置要求说明

名称	位置	要求	说明
`uploadId`	路径	必填	不透明的可恢复上传会话 ID。字符串不透明的可恢复上传会话 ID。最短长度：`1` 最长长度：`200` 字段示例 `[ "upl_0123456789abcdef01234567" ]`

uploadId

路径

必填

不透明的可恢复上传会话 ID。

字符串

不透明的可恢复上传会话 ID。

最短长度：1

最长长度：200

字段示例

[
  "upl_0123456789abcdef01234567"
]

响应

200 上传会话

application/json对象

可恢复上传会话状态。

属性要求类型与说明

id

必填

字符串

可恢复上传会话 ID。

字段示例

[
  "upl_0123456789abcdef01234567"
]

status

必填

字符串

可恢复上传会话生命周期状态。processing 表示字节已提交，正在完成泼溅处理。

可选值："created" "uploading" "processing" "completed" "canceled"

字段示例

[
  "created"
]

contentLength

必填

整数 / 空值

创建上传时声明的源文件总字节数，客户端未提供时为 null。

可选结构 1

整数

最小值：0

最大值：25000000000

可选结构 2

空值

字段示例

[
  null
]

sourceFormat

必填

字符串

上传文件格式。原始高斯泼溅 PLY 文件使用 ply，SOG 文件使用 sog，SuperSplat 导出的 SSOG 归档使用 ssog，LCC 归档使用 lcc。

可选值："ply" "sog" "ssog" "lcc"

字段示例

[
  "ply"
]

title

必填

字符串

新泼溅将使用的展示标题。

字段示例

[
  "garden-scan"
]

description

必填

字符串

新泼溅将使用的展示描述。

字段示例

[
  ""
]

softwareTools

可选

数组

为新泼溅署名的可选软件目录 ID。通过软件目录端点获取当前支持的 ID；由于目录可能扩展，此字段不是 OpenAPI 枚举。

最多项目：6

数组项目不得重复。

数组项目结构

字符串

软件目录 ID。

最短长度：1

最长长度：64

格式规则："^[a-z0-9][a-z0-9-]{0,63}$"

字段示例

[
  "lcc-studio"
]

字段示例

[
  [
    "lcc-studio"
  ]
]

partSize

必填

整数

服务器选定的每分片目标字节数，用于拆分文件的分片范围，最后一个分片可更小。

最小值：1

最大值：25000000000

字段示例

[
  67108864
]

uploadedParts

必填

数组

服务器已检测到的分片，用于恢复中断的上传。

数组项目结构

对象

属性要求类型与说明

partNumber

必填

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

etag

必填

字符串

已上传分片的 ETag。

字段示例

[
  "\"abc123\""
]

size

可选

整数

实际检测到的此分片字节数，若已知。这是恢复元数据，并非目标分片尺寸。

最小值：0

最大值：25000000000

字段示例

[
  67108864
]

expiresAt

必填

字符串

上传会话过期时间。

字段示例

[
  "2026-01-01T00:00:00.000Z"
]

上传会话

{
  "id": "upl_0123456789abcdef01234567",
  "status": "uploading",
  "contentLength": 125829120,
  "sourceFormat": "ply",
  "title": "Garden scan",
  "description": "",
  "partSize": 67108864,
  "uploadedParts": [
    {
      "partNumber": 1,
      "etag": "\"abc123\"",
      "size": 67108864
    }
  ],
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

404 未找到

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

未找到资源

{
  "error": "Resource not found"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

为上传分片创建签名 URL

POST /v1/splats/uploads/{uploadId}/part-upload-urls

返回请求分片编号对应的签名 URL。通过 HTTP PUT 将各分片上传到对应地址，并保存返回的 ETag 用于完成上传。

请求参数

名称位置要求说明

名称	位置	要求	说明
`uploadId`	路径	必填	不透明的可恢复上传会话 ID。字符串不透明的可恢复上传会话 ID。最短长度：`1` 最长长度：`200` 字段示例 `[ "upl_0123456789abcdef01234567" ]`

uploadId

路径

必填

不透明的可恢复上传会话 ID。

字符串

不透明的可恢复上传会话 ID。

最短长度：1

最长长度：200

字段示例

[
  "upl_0123456789abcdef01234567"
]

请求体（必填）

application/json对象

为指定上传分片创建签名 URL 的请求体。

不允许额外属性。

属性要求类型与说明

属性	要求	类型与说明
`parts`	必填	数组需要创建签名 URL 的分片编号，从 1 开始。使用会话的 `partSize` 拆分源文件计算编号，仅请求已经准备好上传的分片。最少项目：`1` 最多项目：`100` 数组项目结构整数分片上传中的分片编号，从 1 开始。最小值：`1` 最大值：`10000` 字段示例 `[ 1 ]`

parts

必填

数组

需要创建签名 URL 的分片编号，从 1 开始。使用会话的 partSize 拆分源文件计算编号，仅请求已经准备好上传的分片。

最少项目：1

最多项目：100

数组项目结构

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

前两个分片

{
  "parts": [
    1,
    2
  ]
}

响应

200 上传分片的签名 URL

application/json对象

上传分片数据的签名 URL。

属性要求类型与说明

uploadId

必填

字符串

可恢复上传会话 ID。

字段示例

[
  "upl_0123456789abcdef01234567"
]

partSize

必填

整数

服务器选定的每分片目标字节数，与上传会话的 partSize 一致。

最小值：1

最大值：25000000000

字段示例

[
  67108864
]

urls

必填

数组

请求的分片编号对应的签名 URL。

数组项目结构

对象

属性要求类型与说明

partNumber

必填

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

url

必填

字符串

签名 URL，通过 HTTP PUT 上传此分片字节。

字段示例

[
  "https://example-bucket.s3.amazonaws.com/uploads/part-1"
]

expiresAt

必填

字符串

此签名 URL 的过期时间。

字段示例

[
  "2026-01-01T00:20:00.000Z"
]

分片签名 URL

{
  "uploadId": "upl_0123456789abcdef01234567",
  "partSize": 67108864,
  "urls": [
    {
      "partNumber": 1,
      "url": "https://example-bucket.s3.amazonaws.com/uploads/part-1",
      "expiresAt": "2026-01-01T00:20:00.000Z"
    },
    {
      "partNumber": 2,
      "url": "https://example-bucket.s3.amazonaws.com/uploads/part-2",
      "expiresAt": "2026-01-01T00:20:00.000Z"
    }
  ]
}

400 请求错误

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

无效请求

{
  "error": "Invalid request"
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

404 未找到

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

未找到资源

{
  "error": "Resource not found"
}

409 状态冲突

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

无效上传状态

{
  "error": "Invalid upload state"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}

完成可恢复上传并发布泼溅

POST /v1/splats/uploads/{uploadId}/complete

完成分片上传并创建泼溅。使用返回的 splatId 获取泼溅详情；PlayCanvas 准备最终查看器资源时，状态可能保持为 processing。

请求参数

名称位置要求说明

名称	位置	要求	说明
`uploadId`	路径	必填	不透明的可恢复上传会话 ID。字符串不透明的可恢复上传会话 ID。最短长度：`1` 最长长度：`200` 字段示例 `[ "upl_0123456789abcdef01234567" ]`

uploadId

路径

必填

不透明的可恢复上传会话 ID。

字符串

不透明的可恢复上传会话 ID。

最短长度：1

最长长度：200

字段示例

[
  "upl_0123456789abcdef01234567"
]

请求体（必填）

application/json对象

完成可恢复上传并将泼溅加入处理队列的请求体。

不允许额外属性。

属性要求类型与说明

parts

必填

数组

待提交的已上传分片，包含每个分片编号及其 S3 ETag。

最少项目：1

最多项目：10000

数组项目结构

对象

不允许额外属性。

属性要求类型与说明

partNumber

必填

整数

分片上传中的分片编号，从 1 开始。

最小值：1

最大值：10000

字段示例

[
  1
]

etag

必填

字符串

此分片上传后 S3 返回的 ETag。

最短长度：1

字段示例

[
  "\"abc123\""
]

已上传分片的 ETag

{
  "parts": [
    {
      "partNumber": 1,
      "etag": "\"abc123\""
    }
  ]
}

响应

200 上传已完成

响应头

Location：新建泼溅资源的 API URL。

application/json对象

上传完成结果，使用返回的 splatId 获取泼溅详情。

属性	要求	类型与说明
`uploadId`	必填	字符串可恢复上传会话 ID。字段示例 `[ "upl_0123456789abcdef01234567" ]`
`status`	必填	字符串完成后的上传会话状态。固定值：`"completed"`
`splatId`	必填	字符串不透明的公开泼溅 ID。使用 `GET /v1/splats/{splatId}` 获取泼溅详情。字段示例 `[ "a1b2c3d4" ]`
`editUrl`	必填	字符串上传完成后，创建者继续编辑泼溅的 URL。字段示例 `[ "https://superspl.at/scene/a1b2c3d4/edit" ]`

已完成的上传

{
  "uploadId": "upl_0123456789abcdef01234567",
  "status": "completed",
  "splatId": "a1b2c3d4",
  "editUrl": "https://superspl.at/scene/a1b2c3d4/edit"
}

201 上传完成，泼溅已排队处理

响应头

Location：新建泼溅资源的 API URL。

application/json对象

上传完成结果，使用返回的 splatId 获取泼溅详情。

属性	要求	类型与说明
`uploadId`	必填	字符串可恢复上传会话 ID。字段示例 `[ "upl_0123456789abcdef01234567" ]`
`status`	必填	字符串完成后的上传会话状态。固定值：`"completed"`
`splatId`	必填	字符串不透明的公开泼溅 ID。使用 `GET /v1/splats/{splatId}` 获取泼溅详情。字段示例 `[ "a1b2c3d4" ]`
`editUrl`	必填	字符串上传完成后，创建者继续编辑泼溅的 URL。字段示例 `[ "https://superspl.at/scene/a1b2c3d4/edit" ]`

已排队处理

{
  "uploadId": "upl_0123456789abcdef01234567",
  "status": "completed",
  "splatId": "a1b2c3d4",
  "editUrl": "https://superspl.at/scene/a1b2c3d4/edit"
}

400 请求错误

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

无效请求

{
  "error": "Invalid request"
}

401 需要身份认证

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

需要身份认证

{
  "error": "Unauthorized"
}

403 禁止访问

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

缺少权限

{
  "error": "Forbidden"
}

404 未找到

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

未找到资源

{
  "error": "Resource not found"
}

409 状态冲突

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

无效上传状态

{
  "error": "Invalid upload state"
}

413 超过上传限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

上传内容过大

{
  "error": "Upload size limit exceeded"
}

429 请求受到速率限制

application/json对象

错误响应。

属性	要求	类型与说明
`error`	必填	字符串便于阅读的错误信息。

超过速率限制

{
  "error": "Too many requests"
}