Skip to content
On this page

Videos

You can manage the videos within your content library by making the following requests:

POST /videos

Add a video to your account. We assume this is a video on-demand, unless you specify otherwise (see below).

VOD

Required parameters

KeyTypeDescription
nameStringIts title (1-100 characters)
inputStringWhere we can fetch it from. Either:
- A URL e.g. https://www.dropbox.com/my-video.mp4?dl=1
- A reference to an upload e.g vidbeo://uploads/abcde12345abcde12345a

Optional parameters

KeyTypeDescription
descriptionStringThe description to give to this video
privacyStringCurrently we support "public", "private", "password" or "authenticated". If set as authenticated, the viewer will need to provide either a cookie or JWT when requesting a landing page, embed code or HLS manifest URL. The default is "private"
passwordStringIf you set the value of privacy as "password", you will need to send that password too. This value should be at least 8 characters. It should contain at least one letter and at least one number
sphericalBooleanWas the video shot in 360?
projectionStringIf the video was shot in 360, the projection used: we currently only support "equirectangular" so please send that for now
languageStringThe language the audio is in. For example:
"en-US" English - United States
"es-ES" Spanish - Spain
"pt-BR" Portuguese - Brazil
"en-GB" English - Great Britain
"en-AU" English - Australia
"en-IN" English - India
"hi-IN" Hindi - India
"fr-FR" French - France
"de-DE" German - Germany
"it-IT" Italian - Italy
tagsArrayAn array of up to ten lowercase, single-word, alphanumeric strings

Example request (video already online)

For a video that can be fetched from https://www.example.com/video.mp4:

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"input":"https://www.example.com/video.mp4", "name":"New video"}' \
"https://api.vidbeo.com/v2/videos"

Example request (video not already online)

For a video on your computer:

  1. Request an upload ID. See POST /uploads
  2. Upload the video to the URL that gives you
  3. Send a reference to the uploaded file in your API call, like this: vidbeo://uploads/UPLOAD-ID-GOES-HERE
shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"input":"vidbeo://uploads/abcde12345abcde12345a", "name":"New video"}' \
"https://api.vidbeo.com/v2/videos"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "type": "vod",
    "name": "New video",
    "description": "",
    "outputs": [],
    "thumbnail": "",
    "sprite": "",
    "duration": 0,
    "privacy": "private",
    "tracks": [],
    "categories": [],
    "enabled": true,
    "transcoder": "",
    "content_rating": "all",
    "spherical": false,
    "projection": "",
    "language": "",
    "cards": [],
    "gates": [],
    "hotspots": [],
    "chapters": [],
    "page_url": "",
    "progress": 0,
    "status": "preparing",
    "tags": [],
    "scheduled_time": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

The most important attribute returned is id. This is the unique identifier that this video has now been assigned. You can then use that, via GET /videos/:id to get the details of this video.

A video file needs to be transcoded before it is available to watch online. Once it is picked up for processing, the system will attempt to download the source file from your provided input. Assuming it can do so, it will verify the file. Assuming it is a supported format it will then be transcoded into various formats to make it suitable for delivery over the web. A thumbnail frame will be extracted to represent it too.

You will see that its status attribute will update to be ready once the video has successfully transcoded, or error if this failed.

Live

NOTE

Live streaming currently requires an Enterprise account.

When you call POST /videos without specifying a type, we assume it is "vod". Therefore you must set its type, as "stream". Creating a stream will automatically create a stream key.

Required parameters

KeyTypeDescription
nameStringA short title
typeStringSet this as "stream"

Optional parameters

KeyTypeDescription
scheduled_timeStringYou can specify when the stream will start as an ISO date string

The default is to generate a video on-demand of your live stream. That usually takes a few minutes after you stop streaming. If you have broadcast on a platform like Twitch before, this is that kind of workflow. However the video of the live stream can be discarded/deleted. That option can be updated afterwards (in the stream_key's settings).

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"My live stream", "type": "stream"}' \
"https://api.vidbeo.com/v2/videos"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "type": "stream",
    "name": "My live stream",
    "input": "vidbeo://stream_keys/its-id-here",
    "description": "",
    "outputs": [],
    "thumbnail": "",
    "sprite": "",
    "duration": 0,
    "privacy": "private",
    "tracks": [],
    "categories": [],
    "enabled": true,
    "transcoder": "",
    "content_rating": "all",
    "spherical": false,
    "projection": "",
    "language": "",
    "cards": [],
    "gates": [],
    "hotspots": [],
    "chapters": [],
    "page_url": "",
    "progress": 100,
    "status": "ready",
    "tags": [],
    "scheduled_time": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

The important part is the value returned for input like vidbeo://stream_keys/its-id-here. That is an internal reference to a stream key to avoid revealing its details here. To get the URL and secret key for OBS (or other streaming application) you need to fetch it using that ID its-id-here. That will provide you with its rtmps_url and rtmps_key.

GET /videos

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/videos"

Example response

json
{
    "success": true,
    "result": [
        {
            "id": "abcde12345abcde12345a",
            "type": "vod",
            "name": "Example video",
            "description": "",
            "outputs": [
                {
                    "label": "hls_ts",
                    "url": "https://cdn.example.com/hls.m3u8"
                }
            ],
            "thumbnail": "https://cdn.example.com/thumbnail.jpg",
            "sprite": "",
            "duration": 123,
            "privacy": "private",
            "tracks": [
                {
                    "id": "abcde12345abcde12345a",
                    "kind": "subtitles",
                    "label": "English",
                    "language": "en-US",
                    "url": "https://cdn.example.com/captions.vtt",
                    "auto_generated": false
                }
            ],
            "categories": [],
            "enabled": true,
            "transcoder": "",
            "content_rating": "all",
            "spherical": false,
            "projection": "",
            "language": "",
            "cards": [],
            "gates": [],
            "hotspots": [],
            "chapters": [],
            "page_url": "",
            "progress": 100,
            "status": "ready",
            "tags": [],
            "scheduled_time": "",
            "created_by": "abcde12345abcde1234a",
            "created_time": "2022-01-01T00:00:00.000Z",
            "updated_by": "abcde12345abcde12345a",
            "updated_time": "2022-01-01T00:00:00.000Z"
        },
        ...
    ],
    "links": {},
    "errors": []
}

Optional parameters

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""Used to get the next page of results: if applicable we return this as part of the links.next URL

GET /videos/:id

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "type": "vod",
    "name": "Example video",
    "description": "",
    "outputs": [
      {
        "label": "hls_ts",
        "url": "https://cdn.example.com/hls.m3u8"
      }
    ],
    "thumbnail": "https://cdn.example.com/thumbnail.jpg",
    "sprite": "",
    "duration": 123,
    "privacy": "private",
    "tracks": [
      {
        "id": "abcde12345abcde12345a",
        "kind": "subtitles",
        "label": "English",
        "language": "en-US",
        "url": "https://cdn.example.com/captions.vtt",
        "auto_generated": false
      }
    ],
    "categories": [],
    "enabled": true,
    "transcoder": "",
    "content_rating": "all",
    "spherical": false,
    "projection": "",
    "language": "",
    "cards": [],
    "gates": [],
    "hotspots": [],
    "chapters": [],
    "page_url": "",
    "progress": 100,
    "status": "ready",
    "tags": [],
    "scheduled_time": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

Response format

KeyTypeDescription
idStringThe unique identifier given to this video
typeStringThis can be "vod" (the default) or "stream" (if live streaming is included in your package)
nameStringThe name given to this video
descriptionStringThe description given to this video
inputStringFor a 'vod', either an upload ID or the URL to fetch the file from. For a live 'stream', the URL to ingest the stream from. This field may not be returned as it may contain authentication data
outputsArrayURLs for the generated versions of the uploaded video file, once it has been processed. A combination of .mpd, .m3u8 and .mp4
thumbnailStringIf one is available, a .jpg image, extracted at source size
spriteStringIf one is available, a .jpg image that contains a grid of preview images
durationNumberThe video's duration, in seconds
privacyStringAccsss to the video. Either "public", "private", "password" or "authenticated"
tracksArrayAny captions or subtitles, each as an object
categoriesArrayAn optional array of categories (selected from those listed within categories)
enabledBooleanA video can be temporarily disabled to block access to it rather than deleting it
transcoderStringSet if a custom profile was used to transcode the video's files
content_ratingStringEither 'all' or 'mature': we default to 'all'
sphericalBooleanWas this video filmed in 360? degress
projectionStringIf this video is 360, what projction is used? Assumed "equirectangular"
languageStringThe language the audio is in. For example:
"en-US" English - United States
"es-ES" Spanish - Spain
"pt-BR" Portuguese - Brazil
"en-GB" English - Great Britain
"en-AU" English - Australia
"en-IN" English - India
"hi-IN" Hindi - India
"fr-FR" French - France
"de-DE" German - Germany
"it-IT" Italian - Italy
cardsArrayInteractive content: each element is an object containing the details of a single card
gatesArrayInteractive content: each element is an object containing the details of a single gate
hotspotsArrayInteractive content: each element is an object containing the details of a single hotspot
chaptersArrayEach element is an object containing the details of one chapter
page_urlStringThe URL of the page on your site you have embedded this video on, which we can then use to automatically build metadata for you
progressIntFor a vod: the percentage transcoded (will be 0 initially, then 100 once completed)
statusStringFor a vod: this can be either "preparing", "processing", "ready" or "error". A live stream can be "offline" or "live"
tagsArrayEach element is a lowercase alphanumeric string
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe date and time it was last modified

PATCH /videos/:id

The body of the request should contain one, or more, attributes that you would like to update for the video. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.

Some fields can only be set by the system. For example:

  • outputs This is managed by the system. The system may update it, for example as new files become available during processing/archiving.
  • progress This is managed by the system: it indicates the percentage progress of the current operation (generally when transcoding).
  • status This is managed by the system: it indicates the status of the current operation.
  • sprite This is managed by the system: a sprite may be generated as part of the transcoding process.

And some of the video's fields are updated using separate API endpoints to make them easier to manage (for example when adding interactive content).

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"name":"New name"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "type": "vod",
    "name": "New name",
    "description": "",
    "outputs": [
      {
        "label": "hls_ts",
        "url": "https://cdn.example.com/hls.m3u8"
      }
    ],
    "thumbnail": "https://cdn.example.com/thumbnail.jpg",
    "sprite": "",
    "duration": 123,
    "privacy": "private",
    "tracks": [
      {
        "id": "abcde12345abcde12345a",
        "kind": "subtitles",
        "label": "English",
        "language": "en-US",
        "url": "https://cdn.example.com/captions.vtt",
        "auto_generated": false
      }
    ],
    "categories": [],
    "enabled": true,
    "transcoder": "",
    "content_rating": "all",
    "spherical": false,
    "projection": "",
    "language": "",
    "cards": [],
    "gates": [],
    "hotspots": [],
    "chapters": [],
    "page_url": "",
    "progress": 100,
    "status": "ready",
    "tags": [],
    "scheduled_time": "",
    "created_by": "abcde12345abcde1234a",
    "created_time": "2022-01-01T00:00:00.000Z",
    "updated_by": "abcde12345abcde12345a",
    "updated_time": "2022-01-01T00:00:00.000Z"
  },
  "links": null,
  "errors": []
}

DELETE /videos/:id

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}

POST /videos/:id/tracks

NOTE

Currently tracks are only supported for video on-demand (type 'vod').

According to the HLS specification Apple insists that subtitles use the WebVTT format (.vtt). So please make sure your WebVTT .vtt file is valid before uploading it. You can paste its content into a free online validator such as https://quuz.org/webvtt/ to make sure.

If your WebVTT .vtt file is not already available online (such as from Dropbox) for us to fetch it, you will need to upload it first. To upload it to us:

  1. Request an upload ID. See POST /uploads
  2. Upload the file to that URL
  3. Send us a reference to it, formatted as shown below

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"label": "English", "language": "en-US", "kind": "subtitles", "url": "vidbeo://uploads/abcde12345abcde12345a", "auto_generated": false}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/tracks"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "label": "English",
    "language": "en",
    "kind": "subtitles",
    "url": "https://www.example.com/english.vtt",
    "auto_generated": false
  },
  "links": null,
  "errors": []
}

Required parameters

KeyTypeDescription
labelStringA short label that will be shown in the player, like "English"
languageStringTheir language. For example:
"en-US" English - United States
"es-ES" Spanish - Spain
"pt-BR" Portuguese - Brazil
"en-GB" English - Great Britain
"en-AU" English - Australia
"en-IN" English - India
"hi-IN" Hindi - India
"fr-FR" French - France
"de-DE" German - Germany
"it-IT" Italian - Italy
kindStringWe currently only support "subtitles"
urlStringEither a full URL we can fetch the .vtt from or a reference to an upload you have just sent it to
auto_generatedBooleanWhether to generate the track using AI (currently not supported for this endpoint so please send false)

DELETE /videos/:id/tracks/:id

Delete a track (subtitles or captions).

The first :id is the ID of the video. The second :id is the ID of the track to delete from it.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/tracks/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}

POST /videos/:id/thumbnail

NOTE

For video on-demand, our system will automatically set a thumbnail image for you as part of the transcoding process.

If you want to replace it, you can ask for another frame within the video (by sending a HH:MM:SS time-code in place of a file URL) or by uploading an image. Any image must be a JPEG (a .jpg) and be under 100KB in size. We recommend using one that is the same dimensions of the video (normally 1280x720 or 1920x1080).

If your .jpg file is not already available from a URL (such as on Dropbox) for us to fetch it from, you will need to upload it to us first. So:

  1. Request an upload ID. See POST /uploads
  2. Upload the image to that URL
  3. Send a reference to the uploaded file, formatted as shown below

Example request 1

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"url": "vidbeo://uploads/abcde12345abcde12345a"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/thumbnail"

Example response 1

json
{
  "success": true,
  "result": {
    "url": "https://www.example.com/frame.jpg"
  },
  "links": null,
  "errors": []
}

Example request 2

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"url": "00:00:52"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/thumbnail"

Example response 2

json
{
  "success": true,
  "result": {
    "url": ""
  },
  "links": null,
  "errors": []
}

Required parameters

KeyTypeDescription
urlStringEither a HH:MM:SS timecode or the URL to fetch your .jpg from or a reference to your prior upload of it to our system

POST /videos/:id/cards

NOTE

Currently cards are only supported for video on-demand (of type 'vod').

We position the card in the corner of the video. Since the video needs to be embedded at a sufficiently large size to see the card, they generally only work on desktops.

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "A card", "show_at": 00:00:20", "hide_at": "00:00:30", "skip": true, "top_text": "Visit our site", "bottom_text": "Find out more", "link": "https://www.example.com"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/cards"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "A card",
    "show_at": "00:00:20",
    "hide_at": "00:00:30",
    "skip": true,
    "top_text": "Visit our site",
    "bottom_text": "Find out more",
    "link": "https://www.example.com"
  },
  "links": null,
  "errors": []
}

Required parameters

We require all the parameters to be sent, even if empty:

KeyTypeDescription
nameStringA short label for the card
show_atStringThe time-code the card should appear
hide_atStringThe time-code the card should disappear if not manually skipped
skipBooleanShould the player add a cross icon to let the viewer skip it?
top_textStringA few words of main text at the top of the card
bottom_textStringSome smaller sub text
linkStringThe URL viewers will be taken to if they click the card

PATCH /videos/:id/cards/:id

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"show_at": "00:00:05"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/cards/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "A card",
    "show_at": "00:00:05",
    "hide_at": "00:00:30",
    "skip": true,
    "top_text": "Visit our site",
    "bottom_text": "Find out more",
    "link": "https://www.example.com"
  },
  "links": null,
  "errors": []
}

DELETE /videos/:id/cards/:id

Using this endpoint, the first :id is the ID of your video. The second :id is the ID of the card to delete from it.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/cards/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}

POST /videos/:id/gates

A gate is used to ask the viewer for some information, likely their email address.

It covers the entire video. Since the video needs to be embedded at a sufficiently large size for the gate's form fields to be usable, they generally only work on desktops.

For privacy, we do not store your viewer's submissions. The submitted data is sent to a service you have already connected to your account (for example Mailchimp). Hence when creating the gate we need you to provide the unique ID of that service as connect_service_id. Generally you will be adding the viewer's data to an existing mailing list of contacts and so we need to know its ID too: pass that as connect_list_id.

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "A gate", "show_at": "00:00:00", "skip": true, "top_text": "Please enter your email", "bottom_text": "By submitting you consent to us storing your data", "fields": [{"label": "Email", "value": "email"}], "connect_service_id": "abcde12345abcde12345a", "connect_list_id": "abcde12345"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/gates"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "A gate",
    "show_at": "00:00:00",
    "skip": true,
    "top_text": "Please enter your email",
    "bottom_text": "",
    "fields": [
      {
        "label": "Email",
        "value": "email"
      }
    ],
    "connect_service_id": "abcde12345abcde12345a",
    "connect_list_id": "abcde12345"
  },
  "links": null,
  "errors": []
}

Required parameters

We require all the parameters to be sent, even if empty:

KeyTypeDescription
nameStringA short label for the card
show_atStringThe time-code the gate should appear e.g "00:00:00" for pre-roll
skipBooleanShould the player add a cross icon to let the viewer skip it
top_textStringA few words of main text at the top of the gate
bottom_textStringSome smaller sub text
fieldsArrayAn array of objects for the field(s) to ask for, each with a label and value. For example [{"label": "Email", "value": "email"}]
connect_service_idStringThe id of a service connected to your account (such as Mailchimp)
connect_list_idStringThe id of a contacts list (audience) you have within that connected service that the viewer's data will be added to

PATCH /videos/:id/gates/:id

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"show_at": "00:00:05"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/gates/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "A gate",
    "show_at": "00:00:05",
    "skip": true,
    "top_text": "Please enter your email",
    "bottom_text": "",
    "fields": [
      {
        "label": "Email",
        "value": "email"
      }
    ],
    "connect_service_id": "abcde12345abcde12345a",
    "connect_list_id": "abcde12345"
  },
  "links": null,
  "errors": []
}

DELETE /videos/:id/gates/:id

The first :id is the ID of your video. The second :id is the ID of the gate to delete from it.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/gates/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}

POST /videos/:id/hotspots

NOTE

Currently hotspots are only supported for video on-demand (of type 'vod').

For a normal video, the x and y values should be percentages (since we don't know what size the video will ultimately be embedded at, we can't use pixels). For example, a value of 50 for both will put the hotspot in the centre of the video. For 360 video, positioning is more complicated. Two-dimensional x and y percentages would not make sense for a spherical video. So these values need instead to be in degrees. For example, 90.

If you would like this clickable region to be invisible, send "invisible" for opacity. Our default is a translucent circle. We recommend using visible regions to make sure the feature is working as expected and the regions are positioned where you intended. Debugging using invisible regions is considerably harder!

The target value will normally be set as "_parent". That means the same page your video is embedded on (it is embedded in an iframe which is why it is its parent page). But you can also use "_blank" to open it in a new tab/window.

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "Buy this", "show_at": "00:00:10", "hide_at": "00:00:20", "x": 25, "y": 25, "action": "link", "link": "https://www.example.com", "target": "_parent", "opacity": "translucent"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/hotspots"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "Buy this",
    "show_at": "00:00:10",
    "hide_at": "00:00:20",
    "x": 25,
    "y": 25,
    "action": "link",
    "link": "https://www.example.com",
    "target": "_parent",
    "opacity": "translucent"
  },
  "links": null,
  "errors": []
}

Required parameters

We require all these parameters to be sent, even if empty:

KeyTypeDescription
nameStringA short label for the hotspot
show_atStringThe time-code the hotspot should appear
hide_atStringThe time-code the hotspot should disappear
xIntWhere the hotspot should be horizontally positioned (we suggest 25-75)
yIntWhere the hotspot should be vertically positioned (we suggest 25-75)
actionStringWe currently only support "link" however we plan on adding additional functionality
linkStringThe URL viewers will be taken to if they click the hotspot
targetStringWhere a link should open: normally you should use "_parent" however you can use "_blank" to open the link in a new tab/window
opacityStringEither "invisible", "translucent" or "opaque": we recommend "translucent"

PATCH /videos/:id/hotspots/:id

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"show_at": "00:00:05"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/hotspots/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "Buy this",
    "show_at": "00:00:05",
    "hide_at": "00:00:20",
    "x": 25,
    "y": 25,
    "action": "link",
    "link": "https://www.example.com",
    "target": "_parent",
    "opacity": "translucent"
  },
  "links": null,
  "errors": []
}

DELETE /videos/:id/hotspots/:id

The first :id is the ID of your video. The second :id is the ID of the hotspot to delete from it.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/hotspots/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}

POST /videos/:id/chapters

Add a chapter marker. The first one must be set to start at 00:00:00.

Note: Each chapter must be at least 10 seconds and so we recommend only using chapters if your video is longer than 30 seconds.

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "An example", "start": "00:00:00"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/chapters"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "An example",
    "start": "00:00:00"
  },
  "links": null,
  "errors": []
}

Required parameters

We require:

KeyTypeDescription
nameStringA short label for it
startStringWhen it starts, as HH:MM:SS

PATCH /videos/:id/chapters/:id

Example request

shell
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"start": "00:00:05"}' \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/chapters/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {
    "id": "abcde12345abcde12345a",
    "name": "An example",
    "start": "00:00:05"
  },
  "links": null,
  "errors": []
}

DELETE /videos/:id/chapters/:id

The first :id is the ID of your video. The second :id is the ID of the chapter to delete from it.

Example request

shell
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/videos/abcde12345abcde12345a/chapters/abcde12345abcde12345a"

Example response

json
{
  "success": true,
  "result": {},
  "links": null,
  "errors": []
}