api.video

Tools (49)

Extracted live via the executor SDK.

• account.getAccount

  Deprecated. Authenticate and get a token, then you can use the bearer token here to retrieve details about your account.

• analytics.getAnalyticsLiveStreamsLiveStreamId

  List live stream player sessions

• analytics.getAnalyticsSessionsSessionIdEvents

  Useful to track and measure video's engagement.

• analytics.getAnalyticsVideosVideoId

  Retrieve all available user sessions for a specific video. Tutorials that use the analytics endpoint.

• authentication.postAuthApiKey

  To get started, submit your API key in the body of your request. api.video returns an access token that is valid for one hour (3600 seconds). A refresh token is also returned. View a tutorial on authentication. All tutorials using the authentication endpoint

• authentication.postAuthRefresh

  Use the refresh endpoint with the refresh token you received when you first authenticated using the api-key endpoint. Send the refresh token in the body of your request. The api.video API returns a new access token that is valid for one hour (3600 seconds) and a new refresh token.

• captions.deleteVideosVideoIdCaptionsLanguage

  Delete a caption in a specific language by providing the video ID for the video you want to delete the caption from and the language the caption is in.

• captions.getVideosVideoIdCaptions

  Retrieve a list of available captions for the videoId you provide.

• captions.getVideosVideoIdCaptionsLanguage

  Display a caption for a video in a specific language. If the language is available, the caption is returned. Otherwise, you will get a response indicating the caption was not found. Tutorials that use the captions endpoint.

• captions.patchVideosVideoIdCaptionsLanguage

  To have the captions on automatically, use this PATCH to set default: true.

• captions.postVideosVideoIdCaptionsLanguage

  Upload a VTT file to add captions to your video. Read our captioning tutorial for more details.

• chapters.deleteVideosVideoIdChaptersLanguage

  Delete a chapter

• chapters.getVideosVideoIdChapters

  Retrieve a list of all chapters for a specified video.

• chapters.getVideosVideoIdChaptersLanguage

  Chapters help your viewers find the sections of the video they are most interested in viewing. Tutorials that use the chapters endpoint.

• chapters.postVideosVideoIdChaptersLanguage

  Chapters help break the video into sections. Read our tutorial for more details.

• live.deleteLiveStreamsLiveStreamId

  Delete a live stream

• live.deleteLiveStreamsLiveStreamIdThumbnail

  Send the unique identifier for a live stream to delete it from the system.

• live.getLiveStreams

  With no parameters added to the url, this will return all livestreams. Query by name or key to limit the list.

• live.getLiveStreamsLiveStreamId

  Supply a LivestreamId, and you'll get all the details for streaming into, and watching the livestream. Tutorials that use the show livestream endpoint.

• live.patchLiveStreamsLiveStreamId

  Use this endpoint to update the player, or to turn recording on/off (saving a copy of the livestream). NOTE: If the livestream is actively streaming, changing the recording status will only affect the NEXT stream. The public=false 'private livestream' is available as a BETA feature, and should be limited to livestreams of 3,000 viewers or fewer.

• live.postLiveStreams

  A live stream will give you the 'connection point' to RTMP your video stream to api.video. It will also give you the details for viewers to watch the same livestream. The public=false 'private livestream' is available as a BETA feature, and should be limited to livestreams of 3,000 viewers or fewer. See our Live Stream Tutorial for a walkthrough of this API with OBS. Your RTMP endpoint for the livestream is rtmp://broadcast.api.video/s/{streamKey} Tutorials that create live streams.

• live.postLiveStreamsLiveStreamIdThumbnail

  Upload an image to use as a backdrop for your livestream. Tutorials that update live stream thumbnails.

• players.deletePlayersPlayerId

  Delete a player if you no longer need it. You can delete any player that you have the player ID for.

• players.deletePlayersPlayerIdLogo

  Delete logo

• players.getPlayers

  Retrieve a list of all the players you created, as well as details about each one. Tutorials that use the player endpoint.

• players.getPlayersPlayerId

  Use a player ID to retrieve details about the player and display it for viewers.

• players.patchPlayersPlayerId

  Use a player ID to update specific details for a player. NOTE: It may take up to 10 min before the new player configuration is available from our CDN.

• players.postPlayers

  Create a player for your video, and customise it.

• players.postPlayersPlayerIdLogo

  The uploaded image maximum size should be 200x100 and its weight should be 200KB. It will be scaled down to 30px height and converted to PNG to be displayed in the player.

• videos.deleteVideo

  If you do not need a video any longer, you can send a request to delete it. All you need is the videoId. Tutorials using video deletion.

• videos.getVideo

  This call provides the same JSON information provided on video creation. For private videos, it will generate a unique token url. Use this to retrieve any details you need about a video, or set up a private viewing URL. Tutorials using video GET.

• videos.getVideoStatus

  This API provides upload status & encoding status to determine when the video is uploaded or ready to playback. Once encoding is completed, the response also lists the available stream qualities. Tutorials using video status.

• videos.listVideos

  Requests to this endpoint return a list of your videos (with all their details). With no parameters added to this query, the API returns all videos. You can filter what videos the API returns using the parameters described below. We have several tutorials that demonstrate this endpoint.

• videos.patchVideo

  Use this endpoint to update the parameters associated with your video. The video you are updating is determined by the video ID you provide in the path. For each parameter you want to update, include the update in the request body. NOTE: If you are updating an array, you must provide the entire array as what you provide here overwrites what is in the system rather than appending to it. Tutorials using video update.

• videos.patchVideosVideoIdThumbnail

  Pick a thumbnail from the given time code. If you'd like to upload an image for your thumbnail, use the Upload a Thumbnail endpoint. There may be a short delay for the thumbnail to update. Tutorials using Thumbnail picking.

• videos.postVideo

  To create a video, you create its container&parameters first, before adding the video file (exception - when using an existing HTTP source).

  • Videos are public by default. Learn about Private videos
  • Up to 6 responsive video streams will be created (from 240p to 4k)
  • Mp4 encoded versions are created at the highest quality (max 1080p) by default.
  • Panoramic videos are for videos recorded in 360 degrees. You can toggle this after your 360 video upload.
  • Searchable parameters: title, description, tags and metadata

  shell

  $ curl https://ws.api.video/videos \ -H 'Authorization: Bearer {access_token} \ -d '{"title":"My video",     "description":"so many details",    "mp4Support":true}'

  add an URL to upload on creation

  You can also create a video directly from a video hosted on a third-party server by giving its URI in source parameter:

  shell

  $ curl https://ws.api.video/videos \-H 'Authorization: Bearer {access_token} \-d '{"source":"http://uri/to/video.mp4", "title":"My video"}'

  In this case, the service will respond 202 Accepted and ingest the video asynchronously.

  Track users with Dynamic Metadata

  Metadata values can be a key:value where the values are predefined, but Dynamic metadata allows you to enter any value for a defined key. To defined a dynamic metadata pair use: "metadata":[{"dynamicKey": "__dynamicKey__"}]

  The double underscore on both sides of the value allows any variable to be added for a given video session. Added the the url you might have: <iframe type="text/html" src="https://embed.api.video/vod/vi6QvU9dhYCzW3BpPvPsZUa8?metadata[classUserName]=Doug" width="960" height="320" frameborder="0" scrollling="no"></iframe>

  This video session will be tagged as watched by Doug - allowing for in-depth analysis on how each viewer interacts with the videos.

  We have tutorials on:

  • Creating and uploading videos

  • Uploading large videos

  • Using tags with videos

  • Private videos

  • Using Dynamic Metadata

  • Full list of tutorials that demonstrate this endpoint.

• videos.postVideosVideoIdSource

  To upload a video to the videoId you created. Replace {videoId} with the id you'd like to use, {access_token} with your token, and /path/to/video.mp4 with the path to the video you'd like to upload. You can only upload your video to the videoId once.

  bash

  curl https://ws.api.video/videos/{videoId}/source \  -H 'Authorization: Bearer {access_token}' \  -F file=@/path/to/video.mp4

  Tutorials using video upload.

• videos.postVideosVideoIdThumbnail

  The thumbnail is the poster that appears in the player window before video playback begins. This endpoint allows you to upload an image for the thumbnail. To select a still frame from the video using a time stamp, use Pick a Thumbnail to pick a time in the video. Note: There may be a short delay before the new thumbnail is delivered to our CDN. Tutorials using Thumbnail upload.

• videosDelegatedUpload.deleteUploadTokensUploadToken

  Delete an existing upload token. This is especially useful for tokens you may have created that do not expire.

• videosDelegatedUpload.getUploadTokens

  A delegated token is used to allow secure uploads without exposing your API key. Use this endpoint to retrieve a list of all currently active delegated tokens. Tutorials using delegated upload.

• videosDelegatedUpload.getUploadTokensUploadToken

  You can retrieve details about a specific upload token if you have the unique identifier for the upload token. Add it in the path of the endpoint. Details include time-to-live (ttl), when the token was created, and when it will expire.

• videosDelegatedUpload.postUpload

  When given a token, anyone can upload a file to the URI https://ws.api.video/upload?token=<tokenId>.

  Example with cURL:

  curl

  $ curl  --request POST --url 'https://ws.api.video/upload?token=toXXX' --header 'content-type: multipart/form-data' -F file=@video.mp4

  Or in an HTML form, with a little JavaScript to convert the form into JSON:

  html

  <!--form for user interaction--><form name="videoUploadForm" >  <label for=video>Video:</label>  <input type=file name=source/><br/>  <input value="Submit" type="submit"></form><div></div><!--JS takes the form data     uses FormData to turn the response into JSON.    then uses POST to upload the video file.    Update the token parameter in the url to your upload token.    --><script>   var form = document.forms.namedItem("videoUploadForm");	   form.addEventListener('submit', function(ev) {	 ev.preventDefault();     var oOutput = document.querySelector("div"),         oData = new FormData(form);     var oReq = new XMLHttpRequest();	      oReq.open("POST", "https://ws.api.video/upload?token=toXXX", true);     oReq.send(oData);	 oReq.onload = function(oEvent) {       if (oReq.status ==201) {         oOutput.innerHTML = "Your video is uploaded!<br/>"  + oReq.response;       } else {         oOutput.innerHTML = "Error " + oReq.status + " occurred when trying to upload your file.<br \/>";       }     };   }, false);	</script>

  Dealing with large files

  We have created a tutorial to walk through the steps required.

• videosDelegatedUpload.postUploadTokens

  Use this endpoint to generate an upload token. You can use this token to authenticate video uploads while keeping your API key safe. Tutorials using delegated upload.

• webhooks.deleteWebhook

  This endpoint will delete the indicated webhook.

• webhooks.getWebhook

  This call provides the same JSON information provided on Webjhook creation.

• webhooks.listWebhooks

  Requests to this endpoint return a list of your webhooks (with all their details). You can filter what the webhook list that the API returns using the parameters described below.

• webhooks.postWebhooks

  Webhooks can push notifications to your server, rather than polling api.video for changes. We currently offer four events:

  • video.encoding.quality.completed When a new video is uploaded into your account, it will be encoded into several different HLS sizes/bitrates. When each version is encoded, your webhook will get a notification. It will look like { \"type\": \"video.encoding.quality.completed\", \"emittedAt\": \"2021-01-29T16:46:25.217+01:00\", \"videoId\": \"viXXXXXXXX\", \"encoding\": \"hls\", \"quality\": \"720p\"} . This request says that the 720p HLS encoding was completed.
  • live-stream.broadcast.started When a livestream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
  • live-stream.broadcast.ended This event fores when the livestream has finished broadcasting, and the broadcasting parameter flips from false to true.
  • video.source.recorded This event is similar to video.encoding.quality.completed, but tells you if a livestream has been recorded as a VOD.
• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools