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

Params:

BASE-URL:

• Release Candidate (RC): https://sdk-mobile-api-rc.truvideo.com

• Production: https://sdk-mobile-api.truvideo.com

---

YOUR-ACCESS-TOKEN:

Access token provided by the endpoint mentioned on this documentation: [SDK Mobile] - Generate an API Token

---

AMOUNT-OF-PARTS:

Amount of parts of the file. Specify the amount of parts in which you want to upload the file. Can be up to 10000 parts.

• Example:

  • If you need to upload the file in a single part, set amountOfParts to 1.

  • If you need to split the file into 3 parts, set amountOfParts to 3.

Note: This applies to a single file.

---

FILE-TYPE:

File type: for its use you must send the extension.

Extension | Type

MP4 | VIDEO MOV | VIDEO AVI | VIDEO MKV | VIDEO FLV | VIDEO WMV | VIDEO 3GPP | VIDEO WEBM | VIDEO JPG | IMAGE JPEG | IMAGE PNG | IMAGE SVG | IMAGE MP3 | AUDIO WAV | AUDIO AAC | AUDIO FLAC | AUDIO PDF | DOCUMENT

---

METADATA:

Metadata

e.g.

{
    "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.

URL:

• Pre-authenticated URL corresponding to the part coming from the endpoint request /initialize

Disclaimer: The parameters that the pre authenticated URL has are fixed and generated by AWS.

Header:

CONTENT-TYPE:

• Provided by the file to upload

Body:

BINARY:

• Refers to the file itself to be uploaded.

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.

Params:

BASE-URL:

• Release Candidate (RC): https://sdk-mobile-api-rc.truvideo.com

• Production: https://sdk-mobile-api.truvideo.com

---

YOUR-ACCESS-TOKEN:

Access token provided by the endpoint mentioned on this documentation: [SDK Mobile] - Generate an API Token

---

ETAG:

The Etag is provided by the PUT upload endpoint which is done on the client side (STEP 2) as a header. It will be the same for each part.

---

PART-NUMBER:

The part number is the one that you receive on the initialize response.

---

UPLOAD-ID:

The upload id is the one that you receive on the initialize response.

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:

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

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

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

The endpoint upload v1 will be deprecated once the upload v2 is delivered to production.