Upload File
This document outlines the process of uploading media files to the Release Candidate (RC) environment via the /api/media/upload endpoint. This procedure is crucial for transferring media assets, such as images and videos, to the server for storage and processing.
STEP 1: Initialize Upload Endpoint
This endpoint allows you to initialize the upload media file.
Minimum size per part Each part must be at least 5 MB, except for the last part, which can be smaller.
Maximum size per part The maximum size of each part is 5 GB.
Maximum amount of parts You can divide a file into a maximum of 10000 parts, but that is not recommended. For best practice, aim to stay within 25 - 50 parts for large files.
Request
Mandatory fields in
metadata
tags
title
size
duration
creator
includeInReport
isLibrary
resolution field can be optional
Error in case of a missing mandatory field. The size field in this case.
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Missing required metadata fields: size",
"instance": "/api/media/upload/initialize",
"message": "error.missing_metadata_fields",
"params": "upload_initial"
}Example of the initialize request body if you have 3 parts:
{
"amountOfParts": 3,
"fileType": "MP4",
"metadata": {
"title": "title example 2",
"type": "VIDEO",
"resolution": "NORMAL",
"size": 1024,
"metadata": "example metadata",
"tags": {
"tag1": "value1",
"tag2": "value2"
},
"duration": 120,
"creator": "John Doe",
"includeInReport": true,
"isLibrary": true
}
}{
"title": "example title",
"type": "VIDEO",
"resolution": "NORMAL",
"size": 1024, //bytes in binary
"metadata": "example metadata",
"tags": {
"tag1": "value1",
"tag2": "value2"
},
"duration": 120,
"creator": "John Doe",
"includeInReport": true,
"isLibrary": true
}cURL
Method: POST
STEP 2: Client side
HTTP request must be implemented to upload the parts.
File Upload Order When uploading multiple files that are part of a sequence (e.g., a video split into multiple parts), it is essential that the files are uploaded in the correct order matching their sequence number. For example, if a video is divided into three parts, they should be uploaded in the following order:
Part 1: Beginning of the video
Part 2: Middle of the video
Part 3: End of the video
Uploading the files out of order (e.g., Part 1 = Beginning, Part 2 = End, Part 3 = Middle) will result in incorrect processing and playback.
Disclaimer: The parameters that the pre authenticated URL has are fixed and generated by AWS.
cURL
Method: PUT
curl --location --request PUT '{URL}' \
--header 'Content-Type: {CONTENT-TYPE}' \
--data-binary '{BINARY}'STEP 3: Finalize Upload Endpoint
This endpoint allows you to finalize the upload of a media file.
Example of the complete request body if you have 3 parts:
{
"parts": [{
"etag": "94f70fbf20d6908d9f56062a6e9f8034",
"partNumber": 1
},
{
"etag": "94f70fbf20d6908d9f56062a6e9f8034",
"partNumber": 2
},
{
"etag": "94f70fbf20d6908d9f56062a6e9f8034",
"partNumber": 3
}],
"uploadId": "1lKYhUSW.vhyTCsBapXEw0l0VJQpUF_kL98fraxIWgJ2lhoqLnbo6zJYr56Eh6VLVqZLoiDYtEQ3Oh93OwuoItye0AmiwVk1DHpU08UmAcM6PPZc5QiG0FFJpKvL.JBfxE1AJfP.nl549fQnRsjsJrPTgdMn91583nAtoHC.L9I-"
}Response
Example of a successful response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"url": "string",
"transcriptionUrl": "string",
"transcriptionLength": "string",
"metadata": "string",
"tags": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"type": "IMAGE",
"createdDate": "2025-07-03T13:46:52.103Z",
"title": "string",
"subAccountId": "string",
"duration": 0,
"creator": "string",
"includeInReport": true,
"contentType": "string",
"isLibrary": true,
"thumbnailUrl": "string",
"previewUrl": "string"
}If any part of the upload process fails, it is important to follow these steps to ensure the complete sequence is successfully uploaded:
Retry Attempts: Each failed upload attempt should be retried up to 3 times. This allows for temporary issues (e.g., network interruptions) to be resolved without restarting the entire process.
Restarting the Upload: If all 3 retry attempts fail for any part of the sequence, the entire upload process must be restarted from the beginning. This ensures the sequence remains intact and avoids inconsistencies in the uploaded data.
Future Improvements (Phase 2): In a future release (Phase 2), we plan to implement a feature to recreate the failed parts of the upload without restarting the entire process. This enhancement will streamline the process and minimize the need to re-upload already successful parts.
Last updated