Start Upload Group

POST /api/videos/uploads

Create a new direct upload group for one SpatialGen video asset set and register every file that will be uploaded into that group.

Allowed API Key Roles

adminupload

Request Body

• videoName: string, required
• description: string, optional
• layout: "2D" | "MVHEVC" | "SBS" | "TB" | "Separate" | "AIV", required
• perspective: "Regular" | "180" | "360", optional
• folderName: string, optional
• files: array, required, minimum 1 item

Each files[] item accepts:

• fileName: string, required
• fileRole: "video" | "video_left" | "video_right" | "audio" | "subtitle" | "aime" | "fcpxmld", required
• sizeBytes: positive integer, required
• languageTag: string, required for audio and subtitle, omitted for all other file roles

Validation Rules

Layout Rules

• Separate requires exactly one video_left file and exactly one video_right file.
• Separate does not allow video.
• All other layouts require exactly one video file.
• Non-Separate layouts do not allow video_left or video_right.
• AIV must use perspective 180.
• AIV requires either one video file ending in .aivu, or both an aime file and an fcpxmld file.

File Extension Rules

• video: .aivu, .mp4, or .mov
• video_left, video_right: .mp4 or .mov
• audio: .mp4 or .m4a
• subtitle: .srt
• aime: .aime
• fcpxmld: .zip

Metadata File Count Rules

• At most one aime file is allowed per upload group.
• At most one fcpxmld file is allowed per upload group.

Language Code Rules

• audio.languageTag must be one of SpatialGen’s supported language-only tags.
• subtitle.languageTag must be one of SpatialGen’s supported language-only tags.
• Tags are normalized to lowercase before validation.
• audio accepts the same shared language list used in the SpatialGen dashboard, plus zxx for instrumental audio.
• subtitle accepts the shared spoken-language list and does not accept zxx.

Supported language tags include:

• en, es, fr, de, it, ja, ko, pt, ru, zh
• af, am, ar, az, bg, bn, bs, ca, cs, da
• el, et, fa, fi, gu, he, hi, hr, hu, hy
• id, is, ka, kn, lt, lv, ml, mr, ms, nl
• no, pa, pl, ro, sk, sl, sq, sr, sv, sw
• ta, te, th, tl, tr, uk, ur, vi
• zxx for instrumental audio only

Response Shape

• sessionId: string
• expiresAt: string
• videoName: string
• fileCount: number
• files: array of registered upload files

Each returned file includes:

• uploadId: string
• fileRole: string
• fileName: string
• totalBytes: number
• partSizeBytes: number
• totalParts: number
• uploadStrategy: "single_put" | "multipart"
• status: string

Example Request

start-upload.js

fetch('https://spatialgen.com/api/videos/uploads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-SPATIALGEN-APPKEY': apiKey,
  },
  body: JSON.stringify({
    videoName: 'My Spatial Video',
    description: 'Uploaded from our media pipeline',
    layout: 'Separate',
    perspective: 'Regular',
    folderName: 'Launch Assets',
    files: [
      {
        fileName: 'left-eye.mov',
        fileRole: 'video_left',
        sizeBytes: 1287340032,
      },
      {
        fileName: 'right-eye.mov',
        fileRole: 'video_right',
        sizeBytes: 1287341024,
      },
      {
        fileName: 'english-audio.mp4',
        fileRole: 'audio',
        sizeBytes: 187340032,
        languageTag: 'en',
      },
      {
        fileName: 'english-subtitles.srt',
        fileRole: 'subtitle',
        sizeBytes: 2401,
        languageTag: 'en',
      },
    ],
  }),
})

Example Response

start-response.json

{
  "sessionId": "5ea97a59-95e0-4c8b-a634-b0fa9976f6ff",
  "expiresAt": "2026-05-06T18:42:11.000Z",
  "videoName": "My Spatial Video",
  "fileCount": 4,
  "files": [
    {
      "uploadId": "402f0bda-a0fa-4551-ae28-7300ab6678dd",
      "fileRole": "video_left",
      "fileName": "left-eye.mov",
      "totalBytes": 1287340032,
      "partSizeBytes": 104857600,
      "totalParts": 13,
      "uploadStrategy": "multipart",
      "status": "initialized"
    },
    {
      "uploadId": "87ca2d60-52d4-4c36-a5d0-42b9f95b58ba",
      "fileRole": "video_right",
      "fileName": "right-eye.mov",
      "totalBytes": 1287341024,
      "partSizeBytes": 104857600,
      "totalParts": 13,
      "uploadStrategy": "multipart",
      "status": "initialized"
    },
    {
      "uploadId": "f56c0c54-f212-49b2-90f9-56653791f82b",
      "fileRole": "audio",
      "fileName": "english-audio.mp4",
      "totalBytes": 187340032,
      "partSizeBytes": 104857600,
      "totalParts": 2,
      "uploadStrategy": "multipart",
      "status": "initialized"
    },
    {
      "uploadId": "7fc29357-7475-4422-987f-a17d5524d18e",
      "fileRole": "subtitle",
      "fileName": "english-subtitles.srt",
      "totalBytes": 2401,
      "partSizeBytes": 2401,
      "totalParts": 1,
      "uploadStrategy": "single_put",
      "status": "initialized"
    }
  ]
}