Skip to content
SpatialGen API

Overview

Base path /api/videos/uploads

Use the Direct Upload API when you want to upload one complete SpatialGen video asset set directly into SpatialGen-managed storage. A single upload group represents one video and may include:

  • One primary video file (.aivu, .mp4, .mov), or seperate left-eye and right-eye video files.
  • Optional audio files
  • Optional subtitle files
  • Optional single aime metadata file
  • Optional single fcpxmld zip file

Each upload follows four steps:

  1. Create an upload group with POST /api/videos/uploads
  2. For each file, request presigned upload URLs for that file with POST /api/videos/uploads/{uploadSessionId}/files/{uploadId}/part-urls
  3. Upload each file part to the presigned PUT URLs returned from step 2.
  4. Mark each file complete with POST /api/videos/uploads/{uploadSessionId}/files/{uploadId}/complete

When every file in the group is completed successfully, SpatialGen will:

  • Create a new library entry in your Dashboard
  • Verify all files have been uploaded successfully

Allowed API Key Roles

adminupload

These endpoints require an API key with upload permissions.

Authentication

Send your SpatialGen API key in the X-SPATIALGEN-APPKEY header on every request.

headers.js
const headers = {
  'Content-Type': 'application/json',
  'X-SPATIALGEN-APPKEY': apiKey,
}

Workflow Notes

  • uploadSessionId identifies the full upload group for one video.
  • uploadId identifies one file inside that upload group.
  • The part-urls endpoint may be called multiple times for multipart uploads.
  • The complete endpoint should only be called after all parts for a file have been uploaded.
  • The cancel endpoint cancels the entire upload group. A cancelled group cannot be resumed.
  • The upload group expires after 5 days if not completed or cancelled. All partially uploaded files will be deleted.

File Role Rules

  • Separate layout requires exactly one video_left file and one video_right file.
  • All other layouts require exactly one video file.
  • Only one aime file is allowed per upload group.
  • Only one fcpxmld file is allowed per upload group.