Create a Live Stream

May 4, 2020 - Doug Sillars in Authenticate live - create

Live streaming your content is a great way to connect with your audience. In this tutorial, we'll walk through the steps you need to follow to set up a video livestream.

Note: we have example code of setting up a live stream in the browser, with Zoom and with OBS.

Here is the direct link to the technical docs to create a live stream.

In order to establish a video livestream, you must first create a livestream container at api.video. Then you can begin streaming with the tool of your choice. In this example, the live stream will be created with OBS, free and open source software for video streaming.

Creating Live Stream

Step 1: Authenticate

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 in your dashoard.

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: Create the Live Stream

Now we create the live stream. In the JSON parameter, feel free to edit the name of the live stream from "Your Stream Name" to whatever you want to name your stream.

Example - Curl Request

curl -X POST https://sandbox.api.video/live-streams \
-H 'Content-Type: application/json'  \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog'\
-d '{"name":"Your Stream Name"}'

Example - Json Response

{"liveStreamId":"li400mYKSgQ6xs7taUeSaEKr",
"streamKey":"30087931-229e-42cf-b5f9-e91bcc1f7332",
"name":"Your Stream Name",
"Record":false,
"Broadcasting":false,
"Assets":{
"iframe":"<iframe src=\"https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
"player":"https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr",
"hls":"https://live.api.video/li400mYKSgQ6xs7taUeSaEKr.m3u8",
"thumbnail":"https://cdn.api.video/live/li400mYKSgQ6xs7taUeSaEKr/thumbnail.jpg"}}

Now the server is ready to accept our live stream, and once broadcast begins (JSON above shows broadcasting:false), it will be viewable on the urls listed in the JSON response.

Connecting Live Video

The JSON response above lists your live stream's streamKey, which will be needed in OBS to connect your video to the server.

in the OBS application:

Esablish a source. In the sources section, choose a video feed to share. You could choose to share your screen, or to share your camera (on a Mac: Video Capture Device, and then in the "Device" dropdown choose the camera). You should now see the video source in the main OBS window.
Connect OBS to api.video. Under Settings, choose Stream. You'll see a choice for service - choose custom.
The server should be rtmp://broadcast.api.video/s and the streamKey is the value you received in the Json when you created the stream. Click OK to accept the changes.
Press Start Streaming.
Share the embed, iFrame, so that others can watch your stream!

Extra Step: The default video poster that your users will see is api.video branded. You can update the thumbnail with an image of your choice:

curl -X POST  https://sandbox.api.video/live-streams/<liveStreamId>//thumbnail \ 
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog' \
-F file=@/path/to/image>

Conclusion

That's all it takes. We've walked through the process of creating a livestream at api.video, and then how to connect that video's streamKey into OBS. Using OBS, we are then able to broadcast video to all our viewers, who can watch using the player (oriframe) url provided by the api.

Give it a try, and let us know how it worked for you in our community forum. We're also there to help out if you run into any difficulties.

Doug Sillars

Head of Developer Relations