StatusPricing

Stream Video File - Direct Upload for Large File (>5GB)

Suggest Edits

This guide will show you how to upload video files to LiveAPI and get them ready for streaming to your audience.

There are 2 ways to upload a video to LiveAPI:

  1. Upload via 3rd-party URL
  2. Directly upload a file from a local machine
    1. Upload small files that < 5GB.
    2. Upload large files that > 5GB.

This article will explain how to upload large video files (>5GB) directly from a local machine.

For large file, it's common that your or your client's connection may not be reliable enough to transfer lots of gigabytes of videos and if the request fails, you have to start over the uploading process. In order to tackle this, it's better to cut a large file into multiple chunks and upload each chunk. If there is an error in your network connectivity while uploading, you can restart uploading a specific chunk without having to reupload the whole file.

For files that are less than 5GB in size, we recommend using the direct upload using single link for simpler process.

Before You Begin

You need to have access to LiveAPI Access Token. Refer to the Authentication in LiveAPI section to learn how to generate an access token via the LiveAPI dashboard.

Your large files should be broken down into multiple chunks. Each chunk should be under 5GB in size.

Step 1: Create a video object

You can make a POST /videos call to create a new video object.

Sample request: 

curl --location --request POST 'https://api.liveapi.com/videos' \
--header 'Content-Type: application/json' \
--header 'Authorization: {your_authentication}'

Sample Response:

Here you will need the _id of the video object for moving on to the next step. 

{
    "_id": "6215df773a13b3c407dc09u8",
    "playback": {
        "embed_url": "https://player.liveapi.com/vod/620e0ba1ce8f11ddde571d1c/vd9e8fe6e0947811ec82f5",
        "hls_url": "https://video.liveapi.com/620e0ba1ce8f11ddde571d1c/vd9e8fe6e0947811ec82f5.mp4/index.m3u8"
    },
    "user": "620e0ba1ce8f11ddde571d1c",
    "environment": "production",
    "organization": "620e0ba2ce8f11ddde571d1d",
    "creation_time": "2022-02-23T07:17:11.940Z"
}

Step 2: Start multipart upload session

To start to upload your file's chunks to the video object you created in Step 1, use POST /videos/{video-id}/multipart-upload/begin with {video-id} taken from _id in Step 1.

Sample request: 

curl --location --request POST 'https://api.liveapi.com/videos/620e0ba1ce8f11ddde571d1c/multipart-upload/begin' \
--header 'Authorization: {your_authentication}'

Sample Response:

The response contains the key for Step 3. Also refer to expiresAt to know when your upload session will be expired.

{
    "key": "eyJ1cGxvREWSJJ89543IkJuYl9abGdwckV2Q2l6NWNRMlhtMTlGeWFVYW5hZmppSHVoMEM5WGNxYTZUQThobHRpTGl6SS5CMy5YRWlRWlZRS1F3dkxxNEhRVHlZNmlrTzJ4X0dwZWlaNjhkRTE2SENZZTBRR0tKeVBiNWwzWkNJQ1YyUmNoQi5zbG05NnlTIiwia2V5Ijoidm9kX3VwbG9hZHMvNjM0ZTAzZWE1YTZiMDczOWZkMmJhN2E3L3ZkZTViYmYwMzA0ZTliMTFlZDk3MzAubXA0In0=",
    "expiresAt": 1666263955821
}

🚧

Upload session expiration

The Upload session expires after 6 hours from creation time, and you won't be able to upload using the session key anymore.

Step 3: Get upload URL for file's chunks

Once you get the key from Step 2, you can get the upload URL for each chunk by using POST /videos/{video-id}/multipart-upload/get-chunk-upload-url.

Sample request:

Replace the key field with the key from Step 2. For chunkId, it's the order of your chunks, eg. your first chunk will have chunkID = 1, second chunk will have chunkID = 2 and so on.

curl --location --request POST 'https://api.liveapi.com/videos/multipart-upload/get-chunk-upload-url' \
--header 'Authorization: {your_authentication}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": "eyJ1cGxvREWSJJ89543IkJuYl9abGdwckV2Q2l6NWNRMlhtMTlGeWFVYW5hZmppSHVoMEM5WGNxYTZUQThobHRpTGl6SS5CMy5YRWlRWlZRS1F3dkxxNEhRVHlZNmlrTzJ4X0dwZWlaNjhkRTE2SENZZTBRR0tKeVBiNWwzWkNJQ1YyUmNoQi5zbG05NnlTIiwia2V5Ijoidm9kX3VwbG9hZHMvNjM0ZTAzZWE1YTZiMDczOWZkMmJhN2E3L3ZkZTViYmYwMzA0ZTliMTFlZDk3MzAubXA0In0=",
    "chunkId": 1
}'

Sample response:

You can use the upload URL returned here to upload your chunk - see next step.

📘

Each upload URL can be used with one single chunk only. If you have 5 chunks, you need 5 different upload URLs.

{
    "url": "https://liveapi-storage.s3-accelerate.amazonaws.com/vod_uploads/634e03ea5a6b0739fd2ba7a7/vde5bbf0304e9b11ed9730.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAV5BGREJE3VXIKN46%2F20221020%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20221020T103635Z&X-Amz-Expires=1800&X-Amz-Signature=db1b2a0acdfca32e4d01501ccaa83e1a819e86cb5fc4a03578afd896e9f5d6b5&X-Amz-SignedHeaders=host&partNumber=1&uploadId=Bnb_ZlgprEvCiz5cQ2Xm19FyaUanafjiHuh0C9Xcqa6TA8hltiLizI.B3.XEiQZVQKQwvLq4HQTyY6ikO2x_GpeiZ68dE16HCYe0QGKJyPb5l3ZCICV2RchB.slm96yS&x-id=UploadPart"
}

Step 4: Upload file's chunks

After you have created the upload URL for your chunk, you can proceed to upload. Make sure each chunk is less than 5GB.

Sample request:

curl --location -g --request PUT 'https://liveapi-storage.s3-accelerate.amazonaws.com/vod_uploads/634e03ea5a6b0739fd2ba7a7/vde5bbf0304e9b11ed9730.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAV5BGREJE3VXIKN46%2F20221020%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20221020T103635Z&X-Amz-Expires=1800&X-Amz-Signature=db1b2a0acdfca32e4d01501ccaa83e1a819e86cb5fc4a03578afd896e9f5d6b5&X-Amz-SignedHeaders=host&partNumber=1&uploadId=Bnb_ZlgprEvCiz5cQ2Xm19FyaUanafjiHuh0C9Xcqa6TA8hltiLizI.B3.XEiQZVQKQwvLq4HQTyY6ikO2x_GpeiZ68dE16HCYe0QGKJyPb5l3ZCICV2RchB.slm96yS&x-id=UploadPart' \
--header 'Content-Type: video/mp4' \
--data-binary '@/Users/Videos/Demo file.mp4'

Sample response:

The response body for this request is empty, but the response headers contain important data:

< HTTP/1.1 200 OK
< Content-Length: 0
< Connection: keep-alive
< x-amz-id-2: oRCeeqi3Re9dhPEVidz8XJssX94OhVFj/yy0mWrQdXNdVJEWsXVIgBtThDwoEn0ym2CI1By+Fh0=
< x-amz-request-id: XMYDYWK4BH00KJ3B
< Date: Thu, 20 Oct 2022 10:42:59 GMT
< ETag: "7cd3f3a37ccb94ccedfcecad946f5273"
< Server: AmazonS3
< X-Cache: Miss from cloudfront
< Via: 1.1 869c20a0b6637fa4614a52064a4bf808.cloudfront.net (CloudFront)
< X-Amz-Cf-Pop: SIN2-P2
< X-Amz-Cf-Id: 2RfZX6GQkGNZuV9gjDzAjotd9h7qOBHqXiCTmUPkulFUo2OtkXqAJw==

You have to note down the ETag header value and the chunkId for each chunk because we are going to need it later. We suggest you create an array and add this data to that array. For example:

chunkDetails.push({ chunkId: 1, eTag:"7cd3f3a37ccb94ccedfcecad946f5273"});

Repeat Step 3 and 4 until you upload all your chunks.

Step 5: Finish uploading

After you have uploaded all your file's chunks, you can call POST /videos/{video-id}/multipart-upload/complete to let LiveAPI knows you have completed.

For chunks field, you can add the content of the chunkDetails array as mentioned in Step 4.

You can call API to finish the uploading even with expired key.

Sample request:

curl --location --request POST 'https://api.liveapi.com/videos/multipart-upload/complete' \
--header 'Authorization: {your_authentication}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chunks": [
        { "chunkId": 1, "eTag": "\"7cd3f3a37cfkdsaccedfcecad946f5273\"" }
    ],
    "key": "eyJ1cGxvYWFDSAlJ2eEFWc01IOHhnM3IwRzVjRmhhNDRYRHRrTFlFVlp0cGpTblN6WWNKMDJ0TDRNSmUyTWQyY09ZdzlpODAuVmVOMFJBX3NJN0E1elJ5bjdMeUdOT1V5MmVPUXdJd0p1cWhsUEVEWU1PQ3NqR2sudWJyakZlTU1GNWttMVZGUTBBIiwia2V5Ijoidm9kX3VwbG9hZHMvNjM0ZTAzZWE1YTZiMDczOWZkMmJhN2E3L3ZkZTViYmYwMzA0ZTliMTFlZDk3MzAubXA0In0="
}'

Sample response:

{
    "success": true,
    "url": "https://liveapi-storage.s3-accelerate.amazonaws.com/vod_uploads/634e03ea5a6b0739fd2ba7a7/vde5bbf0304e9b11ed9730.mp4"
}

Then you can call to GET /videos/{id} to retrieve the video details with the {id} being the video identifier.

Cancel upload sessions

To cancel ongoing upload sessions you can use POST /videos/multipart-upload/abort. You can call API to abort the session even with expired key.

Sample request:

curl --location --request POST 'https://api.liveapi.com/videos/multipart-upload/abort' \
--header 'Authorization: {your_authentication}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": "eyJ1cGxvYWRJZCI6IlJ2eEFWc01IOHhnM3IwRzVjRmhhNDRYRHRrTFlFVlp0cGpTblN6WWNKMDJ0TDRNSmUyTWQyY09ZdzlpODAuVmVOMFJBX3NJN0E1elJ5bjdMeUdOT1V5MmVPUXdJd0p1cWhsUEVEWU1PQ3NqR2sudWJyakZlTU1GNWttMVZGUTBBIiwia2V5Ijoidm9kX3VwbG9hZHMvNjM0ZTAzZWE1YTZiMDczOWZkMmJhN2E3L3ZkZTViYmYwMzA0ZTliMTFlZDk3MzAubXA0In0="
}'

Sample response:

{
    "success": true
}

📘

Supported Formats

LiveAPI supports all formats which ffmpeg supports. For the full list, you can refer to here.

Webhook supported for Video

You can get a list of webhook events we supported for Video here.

📘

Files are kept 15 days after account is expired

When your subscription plan ends, LiveAPI will continute to store your files for the next 15 days. After that, the files will be deleted permanently.

Updated 6 months ago