api.video
  1. Videos
api.video
  • Account
    • Show account
      GET
  • Analytics
    • List live stream player sessions
      GET
    • List player session events
      GET
    • List video player sessions
      GET
  • Authentication
    • Authenticate
      POST
    • Refresh token
      POST
  • Live
    • List all live streams
      GET
    • Create live stream
      POST
    • Delete a live stream
      DELETE
    • Show live stream
      GET
    • Update a live stream
      PATCH
    • Delete a thumbnail
      DELETE
    • Upload a thumbnail
      POST
  • Players
    • List all players
      GET
    • Create a player
      POST
    • Delete a player
      DELETE
    • Show a player
      GET
    • Update a player
      PATCH
    • Delete logo
      DELETE
    • Upload a logo
      POST
  • Videos - Delegated upload
    • Upload with an upload token
    • List all active upload tokens.
    • Generate an upload token
    • Delete an upload token
    • Show upload token
  • Videos
    • List all videos
      GET
    • Create a video
      POST
    • Delete a video
      DELETE
    • Show a video
      GET
    • Update a video
      PATCH
    • Upload a video
      POST
    • Show video status
      GET
    • Pick a thumbnail
      PATCH
    • Upload a thumbnail
      POST
  • Captions
    • List video captions
    • Delete a caption
    • Show a caption
    • Update caption
    • Upload a caption
  • Chapters
    • List video chapters
    • Delete a chapter
    • Show a chapter
    • Upload a chapter
  • Webhooks
    • List all webhooks
    • Create Webhook
    • Delete a Webhook
    • Show Webhook details
  1. Videos

Create a video

POST
/videos
Videos
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

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:
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.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://ws.api.video/videos' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "An amazing video explaining string theory.",
    "metadata": [
        {
            "key": "Author",
            "value": "John Doe"
        },
        {
            "key": "Format",
            "value": "Tutorial"
        }
    ],
    "mp4Support": true,
    "panoramic": false,
    "playerId": "pl45KFKdlddgk654dspkze",
    "public": false,
    "tags": [
        "maths",
        "string theory",
        "video"
    ],
    "title": "Maths video"
}'
Response Response Example
201 - response
{
  "assets": {
    "hls": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/hls/manifest.m3u8",
    "iframe": "<iframe src=\"//embed.api.video/vi4k0jvEUuaTdRAEjQ4Jfrgz?token=831a9bd9-9f50-464c-a369-8e9d914371ae\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "mp4": "https://cdn.api.video/vod/vi4k0jvEUuaTdRAEjQ4Jfrgz/token/8fd70443-d9f0-45d2-b01c-12c8cfc707c9/mp4/720/source.mp4",
    "player": "https://embed.api.video/vi4k0jvEUuaTdRAEjQ4Jfrgz?token=831a9bd9-9f50-464c-a369-8e9d914371ae",
    "thumbnail": "https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg"
  },
  "description": "An amazing video explaining the string theory",
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "mp4Support": true,
  "panoramic": false,
  "playerId": "pl4k0jvEUuaTdRAEjQ4Jfrgz",
  "public": false,
  "publishedAt": "4665-07-14T23:36:18.598Z",
  "source": {
    "uri": "/videos/vi4k0jvEUuaTdRAEjQ4Jfrgz/source"
  },
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "title": "Maths video",
  "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz"
}

Request

Body Params application/json
description
string 
optional
A brief description of your video.
Example:
A video about string theory.
metadata
array[object (metadata) {2}] 
optional
A list of key value pairs that you use to provide metadata for your video. These pairs can be made dynamic, allowing you to segment your audience. Read more on dynamic metadata.
Example:
[{"key": "Author", "value": "John Doe"}]
key
string 
optional
The constant that defines the data set.
Example:
Color
value
string 
optional
A variable which belongs to the data set.
Example:
Green
mp4Support
boolean 
optional
Enables mp4 version in addition to streamed version.
Default:
true
Example:
true
panoramic
boolean 
optional
Indicates if your video is a 360/immersive video.
Default:
false
Example:
false
playerId
string 
optional
The unique identification number for your video player.
Example:
pl45KFKdlddgk654dspkze
public
boolean 
optional
Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Default is true. Tutorials on private videos.
Default:
true
Example:
true
publishedAt
string <date-time>
optional
The API uses ISO-8601 format for time, and includes 3 places for milliseconds.
Example:
2020-07-14T23:36:18.598Z
source
string 
optional
If you add a video already on the web, this is where you enter the url for the video.
Example:
https://www.myvideo.url.com/video.mp4
tags
array[string]
optional
A list of tags you want to use to describe your video.
Example:
["maths", "string theory", "video"]
title
string 
required
The title of your new video.
Example:
Maths video
Examples

Responses

🟢201Created
application/json
Body
assets
object (videoAssets) 
optional
Collection of details about the video object that you can use to work with the video object.
hls
string <uri>
optional
This is the manifest URL. For HTTP Live Streaming (HLS), when a HLS video stream is initiated, the first file to download is the manifest. This file has the extension M3U8, and provides the video player with information about the various bitrates available for streaming.
iframe
string 
optional
Code to use video from a third party website
Example:
<iframe src="//embed.api.video/c188ed58-3403-46a2-b91b-44603d10b2c9?token=831a9bd9-9f50-464c-a369-8e9d914371ae" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen=""></iframe>
mp4
string <uri>
optional
Available only if mp4Support is enabled. Raw mp4 url.
Example:
https://cdn.api.video/vod/vi4k0jvEUuaTdRAEjQ4Jfrgz/token/8fd70443-d9f0-45d2-b01c-12c8cfc707c9/mp4/720/source.mp4
player
string <uri>
optional
Raw url of the player.
Example:
https://embed.api.video/1b9d6ae8-8f57-4b6d-8552-d636926b4f5f?token=831a9bd9-9f50-464c-a369-8e9d914371ae
thumbnail
string <uri>
optional
Poster of the video.
Example:
https://cdn.api.video/stream/831a9bd9-9f50-464c-a369-8e9d914371ae/thumbnail.jpg
description
string 
optional
A description for the video content.
Example:
An amazing video explaining string theory.
metadata
array[object (metadata) {2}] 
optional
Metadata you can use to categorise and filter videos. Metadata is a list of dictionaries, where each dictionary represents a key value pair for categorising a video. Dynamic Metadata allows you to define a key that allows any value pair.
Example:
[{"key":"Author", "value":"John Doe"}, {"key":"Format", "value":"Tutorial"}]
key
string 
optional
The constant that defines the data set.
Example:
Color
value
string 
optional
A variable which belongs to the data set.
Example:
Green
mp4Support
boolean 
optional
This lets you know whether mp4 is supported. If enabled, an mp4 URL will be provided in the response for the video.
Example:
true
panoramic
boolean 
optional
Defines if video is panoramic.
Example:
false
playerId
string 
optional
The id of the player that will be applied on the video.
Example:
pl45KFKdlddgk654dspkze
public
boolean 
optional
Defines if the content is publicly reachable or if a unique token is needed for each play session. Default is true. Tutorials on private videos.
Example:
false
publishedAt
string 
optional
The date and time the API created the video. Date and time are provided using ISO-8601 UTC format.
Example:
2019-12-16T08:25:51.000Z
source
object (videoSource) 
optional
Source information about the video.
liveStream
object (video_source_live_stream) 
optional
This appears if the video is from a Live Record.
type
string 
optional
uri
string 
optional
The URL where the video is stored.
Example:
/videos/vi4k0jvEUuaTdRAEjQ4Prklg/source
tags
array
optional
One array of tags (each tag is a string) in order to categorize a video. Tags may include spaces.
Example:
"tags": ["maths", "string theory", "video"]
title
string 
optional
The title of the video content.
Example:
Maths video
updatedAt
string <date-time>
optional
The date and time the video was updated. Date and time are provided using ISO-8601 UTC format.
Example:
2019-12-16T08:15:51.000Z
videoId
string 
optional
The unique identifier of the video object.
Example:
vi4k0jvEUuaTdRAEjQ4Prklg
🟢202Accepted
🟠400Bad Request
Modified at 2023-08-15 05:52:15
Previous
List all videos
Next
Delete a video
Built with