Video upload with cURL

March 19, 2020 - Doug Sillars in Video upload, video create, Authenticate, curl

api.video can help you simplify your video hosting and delivery. As such, one of the first things you'll want to do is to upload videos and get them loaded into the service. Once you upload the video, we'll take care of transcoding the video into streams for delivery to your users.

The easiest way to upload videos into api.video is using our API, and we'll walk through the steps to use the API and get your video online in this tutorial.

Using cURL

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

This example works for smaller videos, but as your video gets larger, you will want to break the video into smaller bites (bytes?) to facilitate upload. Here's how do to that using the command line.

Other languages?

We have many tutorials on video upload. Here are a few links to help you:

We have several Clients for additional platforms that will help you get started uploading videos quickly.

You can also check out the API reference documentation for uploading a video here:

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

curl -X POST \
https://sandbox.api.video/auth/api-key \
-H 'Content-Type: application/json' \
-d '{"apiKey": "your_api_key"}'

Example - Http Request

POST /auth/api-key HTTP/1.1
Host: sandbox.api.video
Content-Type: application/json

{
	"apiKey": "your_api_key"
}

Example - Json Response

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog",
    "refresh_token": "def502001d5c8aeb3f921c833f0c90fbbb9ef2be1f25e476d7acf999010c435c043bf382f462bd48e82c9253ee0bcad1dd07c07b827552ef540b1429e032acdb78325d17401d54a4baf421e41eaed4b545938f3539428ea52297cb8760269b95284da8c89c55d72c9584ced47510976a9f3106a034173dd3e39c3bf4f7119c4722fda4f70c15241a392be79ba5a1ff9e4f3edfa204c22ad9f9776258fb511137e6e0f40a917866158bc13c7536243146bb35b5f6edf59f6d2d346721fcbc22810364fdb4236949db605e4eb1de1578af97866e850fe535b1febb21ab52dfc0dfe91719d5c81c477ba4c979c993e404d6ed3e51d549a239cc486c17e5e3f414ad66fa71e1a16eba2124eaaba97fc9c8729109b8294c8a440e0cd78f8c9b0006c15a8e32e19eb364f9d644a3510735301ff525aa856728791b240523f8a85d2a57754c221e49de80b690a5908f3d599b43aec5164bab7dd4dce10b5f336140d32315ba64ee4cf3b68e9babea65f493db6cfb28f53c5e2dcaf440f4509c39bfda2076c6e9b8efcb"
}

Step 2

We will use the create video API to create and upload the video.

The Authorization: Bearer header uses the access_token from the first step. Hint: Make sure to not remove the end ' when pasting in your token. The title parameter is required, so you must add a name to your video. If your video is hosted on a server, you can use "source":"url" in the JSON to add the video. If your video is on your local machine, we'll need to do one additional step.

This example also includes the video description. The response contains links to the video location, and generates a unique identifier videoId.

Curl Request

curl -X POST https://sandbox.api.video/videos \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog' \
  -d '{
    "title":"This is a title",
    "description":"My video description", 
    "source":"https://example.com/myVideo.mp4"
  }'

Http Request

POST /videos HTTP/1.1
Host: sandbox.api.video
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog
Content-Type: application/json

{
    "title":"This is a title",
    "description":"My video description",
    "source":"https://example.com/myVideo.mp4"
}

Example Response

{
    "videoId": "vitq4gOj8GyDT9kyxPQoyNJl",
    "title": "This is a title",
    "description": "My video description",
    "public": true,
    "publishedAt": "2018-05-16T18:47:32+02:00",
    "tags": [],
    "metadata": [],
    "source": {
        "uri": "/videos/vitq4gOj8GyDT9kyxPQoyNJl/source"
    },
    "assets": {
        "iframe": "<iframe src='//embed.api.video/vitq4gOj8GyDT9kyxPQoyNJl' width='100%' height='100%' frameborder='0' scrolling='no' allowfullscreen=''></iframe>",
        "player": "https://embed.api.video/vitq4gOj8GyDT9kyxPQoyNJl",
        "hls": "https://cdn.api.video/stream/vitq4gOj8GyDT9kyxPQoyNJl/hls/manifest.m3u8",
        "thumbnail": "https://cdn.api.video/stream/vitq4gOj8GyDT9kyxPQoyNJl/thumbnail.jpg"
    }
}

Step 3: Upload the video file.

In this step, we use the upload endpoint of the API. You can also use delegated tokens for the upload. The advantage of delegated tokens is that these are safe to use on a webpage (whereas your authorisation token is not), and the videos are directly uploaded to api.video. You can learn more about using delegated tokens for this same experience.

In Step 2, we saw how to link to a video already hosted. If the video is not hosted, and must be uploaded, we will call the video upload API:

curl https://ws.api.video/videos/vitq4gOj8GyDT9kyxPQoyNJl/source \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog' \
  -F file=@/path/to/video.mp4

When the upload is complete, a JSON response similar to that of step 2 is returned.

That's it - if you access the assets links in the response JSON - you can begin sharing the video you just created. Note: The mp4 URL is only added to the API response once the mp4 video has been encoded, which may take a few additional seconds.

Conclusion

In this post, we learned about authentication of our account with our api.video token, creating a video container, and uploading a video into that container. Once your video is uploaded, it is ready to be shared with your audience!

If you have any questions or suggestions, please share them on our commmunity forum. To start building now, singup for an api.video account here. Thanks for reading!