Uploading Videos

Uploading videos at Zustack.

Learn how to upload videos to Zustack using the API.

Video files are uploaded using multipart upload, which splits large files into smaller chunks for more reliable and resumable transfer.

Prerequisites

Before you begin, make sure you have:

A bucket created
A JWT signed with your API Key with the scope claim set to write.

Video Multipart Upload Request

Form Data Parameters

Parameter	Type	Description
`bucket_id`	`string`	The ID of your target bucket.
`access`	`string`	Can be `public` or `private`.
`client_id`	`string`	A unique identifier for your video upload.
`file`	`file`	A single video chunk (`video/*`).
`thumbnail`	`file`	Optional thumbnail image for the video (`image/*`).
`chunk_number`	`string`	The current chunk number (starting from `0`).
`total_chunks`	`string`	Total number of chunks for the upload (starting from `1`).
`resolution`	`string`	Desired video resolution, e.g., `1920x1080` `1280x720`.
`timeline_preview`	`string`	`yes` or `no` whether to generate a timeline preview.

Example Request

Split the video into chunks

Assuming you have a video file, use split to divide it into 5MB chunks with a video file of 10MiB for this example:

mkdir ~/out
cp ~/path/to/video.mkv ~/out/input.mkv
split -b 5M --numeric-suffixes=1 --additional-suffix=.mkv ~/out/input.mkv ~/out/chunk_
mv ~/out/chunk_01.mkv ~/out/video.mkv

Set environment variables

export BUCKET_ID=your_bucket_id
export JWT=your_jwt_token
export ACCESS=public
export CLIENT_ID=some_long_id
export PATH_TO_CHUNK=@/path/to/out/video.mkv
export PATH_TO_THUMBNAIL=@/path/to/image.png
export CHUNK_NUMBER=0
export TOTAL_CHUNKS=2
export RESOLUTION="1920x1080 1280x720"
export TIMELINE_PREVIEW=yes

Send the first chunk

curl -X POST "https://zustack.com/files/upload/video/${BUCKET_ID}" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: multipart/form-data" \
  -F "access=${ACCESS}" \
  -F "client_id=${CLIENT_ID}" \
  -F "chunk_number=${CHUNK_NUMBER}" \
  -F "total_chunks=${TOTAL_CHUNKS}" \
  -F "resolution=${RESOLUTION}" \
  -F "timeline_preview=${TIMELINE_PREVIEW}" \
  -F "file=${PATH_TO_CHUNK};type=video/x-matroska" \
  -F "thumbnail=${PATH_TO_THUMBNAIL}"

Each successful chunk upload will return a 200 OK response.

Send the next chunk

When chunk_number is equal to total_chunks - 1, you’re uploading the final chunk.

mv ~/out/video.mkv ~/out/chunk_01.mkv
mv ~/out/chunk_02.mkv ~/out/video.mkv
export CHUNK_NUMBER=1

curl -X POST "https://zustack.com/files/upload/video/${BUCKET_ID}" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: multipart/form-data" \
  -F "access=${ACCESS}" \
  -F "client_id=${CLIENT_ID}" \
  -F "chunk_number=${CHUNK_NUMBER}" \
  -F "total_chunks=${TOTAL_CHUNKS}" \
  -F "resolution=${RESOLUTION}" \
  -F "timeline_preview=${TIMELINE_PREVIEW}" \
  -F "file=${PATH_TO_CHUNK};type=video/x-matroska" \
  -F "thumbnail=${PATH_TO_THUMBNAIL}"

Response

Response Fields

Field	Type	Description
`file_id`	`string`	A unique ID for the uploaded video
`video_length`	`string`	The duration of the video in seconds

Example Response

{
  "file_id": "2f5c8e31-9d47-402a-995e-8cbbd8120373"
  "video_length": "120"
}

Once the file is uploaded, Zustack will send relevant information about the file to the webhook only if it is configured.

The data sent will include:

file_id: The ID of the created file.
media_url: The URL of the file.
status: The status of the file.

Make sure your bucket’s webhook is properly set up to receive these notifications.

Upload Expiration Reminder

Any video files uploaded using multipart uploads will be automatically deleted after 24 hours if the upload is not completed. Make sure to finalize your upload within this time frame to avoid data loss.