# Overview

> Part of the [SpatialGen API documentation](/index.md). [HTML version of this page](/api/direct-upload/).

Upload one video asset group directly into SpatialGen with multipart-aware file uploads.

## API context

-   API requests use `https://spatialgen.com` with the `/api` path prefix, included once.
-   Authenticate requests to SpatialGen API endpoints with the `X-SPATIALGEN-APPKEY` HTTP header.
-   Use a key from the workspace that owns the requested resources. Follow the roles and scopes specified for each endpoint below.
-   Keep `admin` and `upload` keys on a trusted backend. `readonly` keys may be used in client apps for permitted read operations.
-   Presigned upload URLs have their own authorization. Do not send your SpatialGen API key to those URLs.

See the [API key guide](/guides/get-started.md) for roles, key creation, expiration, revocation, and rotation.

* * *

**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

`admin`, `upload`

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

```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.

## Related Endpoints

-   [Start Upload Group](/api/direct-upload/start/)
-   [Get Part URLs](/api/direct-upload/part-urls/)
-   [Complete File Upload](/api/direct-upload/complete/)
-   [Cancel Upload Group](/api/direct-upload/cancel/)