Video upload (large videos) with cURL

Some videos are large, and when creating and uploading a large video to api.video, there can be transport issues, causing the upload to fail.

When uploading large videos, they must be broken into 100MB chunks to ensure delivery. While these also may fail, the amount of time lost is minimised, and the segement can be retried.

api.video will reassemble the video segments on the server, and create streams for your users to consume.

NOTE: This tutorial walks through the process of partial video uploads using curl. The api.video API Clients handle large video uploads automatically, allowing you to skip this process. While this is a great walkthrough of what the clients and SDKs do behind the scenes, we strongly reccomend that you use them, as getting the Content-Range headers correct (in step 4) is tricky.

This tutorial uses curl and HTTP requests to authenticate your session, create a video, and then upload the video.

Another great way to split up large files is to use JavaScript and Blob.slice. We have a second tutorial for that technique.

Due to limits in how HTTP handles large file uploads, there is an upload limit of 199 MiB per video segment.

However, you can still upload videos over 199 MiB, it just needs to be split into separate chunks (under 200 MiB), and each chunk uploaded separately.

This process works for videos that are less than 200 MiB as well, but has one additional step.

Step 1

You need an access_token in order to create and upload a video.

You will need your API key to obtain the access_token. You can find your API key on your dashboard.

This tutorial uses the sandbox endpoint. To upload your video in production, simply replace all sandbox.api.video instances with ws.api.video.

First, call the authentication endpoint and get your access token.

Example - Curl Request

Example - Http Request

Example - Json Response

Step 2

1. We will use the create API to create a video container.
2. There are many parameters you can use when you create (and upload) a video, but the only required parameter is title (the name of your video).
3. The response contains links to the video location, and generates a unique identifier named videoId.

Curl Request

Http Request

Example Response

Step 3 - Splitting the video

You have created a video container, but have not yet uploaded the video sources. As mentioned, a video over 199 MiB must be split into smaller chunks.

Mac

split is a command line tool built into MacOS.

1. The first argument is the chunk size (here 100MB)
2. The second argument is path to the source file
3. The third argument is a pattern name for the chunked files

This command creates 3 files:

Linux

You can use the split utility to split the video into smaller chunks (max 199 MiB).

1. The first argument is the chunk size (here 100MB)
2. The second argument is path to the source file
3. The third argument is a pattern name for the chunked files

This command generated 3 chunk files:

The last chunk is generally smaller than the other ones.

Windows

There are a number of free tools that can split a file into chunks.

Step 4: Uploading video chunks

We will use the source API to add the source files. Note that the url also contains the videoId parameter obtained in the json response from step 2.

To upload by range, you must add the following header to the request:

Content-Range: bytes <from>-<to>/<total_size>

• from is the 0-indexed start position in the file
• to is the 0-indexed end position in the file
• total_size is the size of the source file. It must be identical across requests.

CURL requests

Request/response 1:

Request/response 2:

Request/response 3

HTTP requests

And there you go. Your large video should be uploaded and ready to go. If you have any questions or suggestions, please share them on our community forum. You can start building now!