发布高斯泼溅

概览

通过代码向 SuperSplat 平台发布 .ply 或 .sog 等高斯泼溅文件，使用的后端与编辑器发布对话框及 superspl.at 的直接上传流程相同。发布后，场景会显示在用户管理页面，并可在 Studio 中配置观看体验。

发布调用的 settings 字段包含体验设置 JSON，与 Studio 写入及 SuperSplat Viewer 读取的格式一致，完整结构详见该参考文档。

流程分为三个主要步骤：

1. 从后端请求签名上传 URL。
2. 使用该 URL 将文件直接上传到 S3。
3. 调用后端 API 启动处理任务。

所有 API 请求都必须在 Authorization 头中包含有效 Bearer 令牌。生成方法详见令牌文档。

路由

获取 AWS S3 签名上传 URL

POST https://playcanvas.com/api/upload/signed-url

Body

{ "fileName": "scene.ply" }

Response

{ "signedUrl": "string", "s3Key": "string" }

示例：

const response = await fetch(`https://playcanvas.com/api/upload/signed-url`, {
    method: 'POST',
    body: JSON.stringify({
        fileName: filename
    }),
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
});

使用签名 URL 上传到 AWS S3

PUT "signedUrl"

Response

{ "signedUrl": "string", "s3Key": "string" }

示例：

const uploadResponse = await fetch(signedUrl, {
    method: 'PUT',
    body: fileData,
    headers: {
        'Content-Type': 'binary/octet-stream'
    }
});

开始处理

POST https://playcanvas.com/api/splats/publish

Body

{
  "s3Key": "string",
  "title": "string",
  "description": "string",
  "listed": boolean,
  "settings": { /* Settings */ },
  "format": "compressed.ply" // or "sog"
}

Settings: 

const settings = {
    camera: {
        fov: 65, // field of view
        position: [1,1,-1], target: [-0.1,0.6,-0.2],
        startAnim: 'none',
        animTrack:null 
    },
    background: {
        color: [0.4,0.4,0.4]
    },
    animTracks:[]
};

Response (Splat data)

{
  "id": "string", 
  "hash": "string",
  "title": "string",
  "description": "string",
  "format": "compressed.ply | sog",
  "version": "string",
  "release_notes": "string",
  "thumbnails": number,
  "size": number,
  "views": number, 
  "comments": number, 
  "starred": number, 
  "listed": boolean,
  "completedAt": DateTime, 
  "createdAt": DateTime, 
  "modifiedAt": DateTime
}

示例：

const response = await fetch(`https://playcanvas.com/api/splats/publish`, {
    method: 'POST',
    body: JSON.stringify({
      s3Key: s3Key,
      title: 'Some Title',
      description: 'Some Description',
      listed: true,
      settings: settings,
      format: format
    }),
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
});

响应示例：

{
  "comments": 0,
  "completedAt": null,
  "createdAt": "2025-10-21T12:42:13.331Z",
  "currentVersion": 1,
  "description": "Some Description",
  "featuredWeight": 0,
  "format": "",
  "hash": "982a2820",
  "hasThumbnails": false,
  "id": 50,
  "listed": true,
  "modifiedAt": "2025-10-21T12:42:13.331Z",
  "releaseNotes": null,
  "size": 0,
  "starred": 0,
  "tags": [],
  "task": { "status": "running", "message": "" },
  "title": "Some Title",
  "url": "https://superspl.at/view?id=982a2820",
  "userId": 7,
  "version": 0,
  "views": 0
}

状态：201，成功。

检查已上传场景的状态

GET https://playcanvas.com/api/splats/{ID}

Response (Splat)


{
  "id": "string",
  "hash": "string",
  "title": "string",
  "description": "string",
  "format": "compressed.ply | sog"
}

示例：

const response = await fetch(`https://playcanvas.com/api/splats/1000`)

错误：

状态码	说明
400	请求无效／请求体无效／超出存储额度。
401	未通过身份验证，令牌缺失或无效。
403	禁止访问。
404	未找到资源，例如 sceneId。
5xx	上传或最终确认期间发生服务器／S3 错误。