Sign up for free

Videos

List all video objects

List all the video objects that are associated with the current workspace.

get /videos
title string

The title of a specific video you want to find. The search will match exactly to what term you provide and return any videos that contain the same term as part of their titles.

Example
"My Video.mp4"
tags[] array[string]

A tag is a category you create and apply to videos. You can search for videos with particular tags by listing one or more here. Only videos that have all the tags you list will be returned.

Example
"[\"captions\", \"dialogue\"]"
metadata object (metadata)

Videos can be tagged with metadata tags in key:value pairs. You can search for videos with specific key value pairs using this parameter. Dynamic Metadata allows you to define a key that allows any value pair.

Example
"metadata[Author]=John Doe&metadata[Format]=Tutorial"
description string

Retrieve video objects by description.

Example
"New Zealand"
liveStreamId string

Retrieve video objects that were recorded from a live stream by liveStreamId.

Example
"li400mYKSgQ6xs7taUeSaEKr"
sortBy string

Use this parameter to sort videos by the their created time, published time, updated time, or by title.

Enum
  • title
  • createdAt
  • publishedAt
  • updatedAt
Example
"publishedAt"
sortOrder string

Use this parameter to sort results. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.

Enum
  • asc
  • desc
Example
"asc"
currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default
1
Example
2
pageSize int

Results per page. Allowed values 1-100, default is 25.

Default
25
Example
30

Requests

<?php
// First install the api client: "composer require api-video/php-api-client"
// Documentation: https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/VideosApi.md#list

require __DIR__ . '/vendor/autoload.php';


$client = new \ApiVideo\Client\Client(
    'https://ws.api.video',
    'YOUR_API_KEY',
    new \Symfony\Component\HttpClient\Psr18Client()
);

// list all videos (all pages)
$allVideos = [];
do {
    $currentPage = $client->videos()->list([]);
    $allVideos = array_merge($allVideos, $currentPage->getData());
} while($currentPage->getPagination()->getCurrentPage() < $currentPage->getPagination()->getPagesTotal());

// list videos that have all the given tags (only first results page)
$videosWithTag = $client->videos()->list(['tags' => ['TAG2','TAG1']]);

// list videos that have all the given metadata values (only first results page)
$videosWithMetadata = $client->videos()->list(['metadata' => ['key1' => 'key1value1', 'key2' => 'key2value1']]);

Responses

ExamplesSchema

Success

{
  "data": [
    {
      "videoId": "vi4blUQJFrYWbaG44NChkH27",
      "playerId": "pl45KFKdlddgk654dspkze",
      "title": "Maths video",
      "description": "An amazing video explaining the string theory",
      "public": false,
      "panoramic": false,
      "mp4Support": true,
      "tags": [
        "maths",
        "string theory",
        "video"
      ],
      "metadata": [
        {
          "key": "Author",
          "value": "John Doe"
        },
        {
          "key": "Format",
          "value": "Tutorial"
        }
      ],
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "updatedAt": "2019-12-16T08:48:49.000Z",
      "source": {
        "uri": "/videos/c188ed58-3403-46a2-b91b-44603d10b2c9/source"
      },
      "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
        "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
        "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
        "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
      }
    },
    {
      "videoId": "vi4blUQJFrYWbaG44NChkH27",
      "title": "Video Title",
      "description": "A description for your video.",
      "public": false,
      "panoramic": false,
      "mp4Support": true,
      "tags": [
        "books",
        "short stories"
      ],
      "metadata": [
        {
          "key": "Author",
          "value": "John Doe"
        },
        {
          "key": "Science Fiction",
          "value": "Cyberpunk"
        },
        {
          "key": "Technology",
          "value": "Computers"
        }
      ],
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "updatedAt": "2019-12-16T08:48:49.000Z",
      "source": {
        "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
      },
      "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
        "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
        "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
        "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
      }
    },
    {
      "videoId": "vi4blUQJFrYWbaG44NChkH27",
      "playerId": "pl45KFKdlddgk654dspkze",
      "title": "My Video Title",
      "description": "A brief description of the video.",
      "public": false,
      "panoramic": false,
      "mp4Support": true,
      "tags": [
        "General",
        "Videos"
      ],
      "metadata": [
        {
          "key": "Length",
          "value": "Short"
        }
      ],
      "publishedAt": "2019-12-16T08:25:51.000Z",
      "updatedAt": "2019-12-16T08:48:49.000Z",
      "source": {
        "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
      },
      "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
        "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
        "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
        "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 11,
    "currentPageItems": 11,
    "links": [
      {
        "rel": "self",
        "uri": "https://ws.api.video/videos?currentPage=1"
      },
      {
        "rel": "first",
        "uri": "https://ws.api.video/videos?currentPage=1"
      },
      {
        "rel": "last",
        "uri": "https://ws.api.video/videos?currentPage=1"
      }
    ]
  }
}

Create a video object

Creates a video object. More information on video objects can be found here.

post /videos
title string

required

The title of your new video.

Example
"Maths video"
description string

A brief description of your video.

Example
"A video about string theory."
source string

You can either add a video already on the web, by entering the URL of the video, or you can also enter the videoId of one of the videos you already have on your api.video acccount, and this will generate a copy of your video. Creating a copy of a video can be especially useful if you want to keep your original video and trim or apply a watermark onto the copy you would create.

Example
"https://www.myvideo.url.com/video.mp4 OR vi4k0jvEUuaTdRAEjQ4JfOyl"
public boolean

Default: True. If set to false the video will become private. More information on private videos can be found here

Default
true
Example
true
panoramic boolean

Indicates if your video is a 360/immersive video.

Default
false
Example
false
mp4Support boolean

Enables mp4 version in addition to streamed version.

Default
true
Example
true
playerId string

The unique identification number for your video player.

Example
"pl45KFKdlddgk654dspkze"
tags array[string]

A list of tags you want to use to describe your video.

Example
"[\"maths\", \"string theory\", \"video\"]"
metadata array[object (Metadata)]

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\"}]"
clip object (clip)

Use this object to create a smaller clip from a video you upload.

  • You can only create video clips in the same request where you create the video container.
  • You cannot update the starting or ending timestamps of a video clip after you created the video container.
  • When you upload a video file into a container where you defined a starting and ending timestamp, the API trims the video according to those timestamps to create a clip.
watermark object (watermark)

Requests

{
  "title": "Maths video",
  "description": "An amazing video explaining string theory.",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "playerId": "pl45KFKdlddgk654dspkze",
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "watermark": {
    "id": "watermark_1BWr2L5MTQwxGkuxKjzh6i",
    "bottom": "10px",
    "right": "10px",
    "width": "50%",
    "opacity": "70%"
  }
}

Responses

ExamplesSchema

Created

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "playerId": "pl4k0jvEUuaTdRAEjQ4Jfrgz",
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "publishedAt": "4665-07-14T23:36:18.598Z",
  "source": {
    "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
  },
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
    "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
    "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
    "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
  }
}

Upload a video

Ingest a video from a source or file.

post /videos/{videoId}/source
file file

required

The path to the video you would like to upload. The path must be local. If you want to use a video from an online source, you must use the "/videos" endpoint and add the "source" parameter when you create a new video.

Example
"@/path/to/video.mp4"

Requests

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/VideosApi.md#upload

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()

      videoId := "vi4k0jvEUuaTdRAEjQ4Jfrgz" 
    // string | Enter the videoId you want to use to upload your video.
      file := os.NewFile(1234, "some_file") 
    // *os.File | The path to the video you would like to upload. The path must be local. If you want to use a video from an online source, you must use the "/videos" endpoint and add the "source" parameter when you create a new video.
    
    
      res, err := client.Videos.UploadFile(videoId, file)
    
      // you can also use a Reader instead of a File:
      // client.Videos.Upload(videoId, fileName, fileReader, fileSize)
    
      if err != nil {
          fmt.Fprintf(os.Stderr, "Error when calling `Videos.Upload``: %v\
", err)
      }
      // response from `Upload`: Video
      fmt.Fprintf(os.Stdout, "Response from `Videos.Upload`: %v\
", res)
    }
      }

Responses

ExamplesSchema

Created

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory.",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "playerId": "pl45KFKdlddgk654dspkze",
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "publishedAt": "4665-07-14T23:36:18.598Z",
  "source": {
    "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
  },
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
    "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
    "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
    "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
  }
}

Upload a thumbnail

Upload a thumbnail for a certain video.

post /videos/{videoId}/thumbnail
file file

required

The image to be added as a thumbnail. The mime type should be image/jpeg, image/png or image/webp. The max allowed size is 8 MiB.

Requests

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/VideosApi.md#uploadThumbnail

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()

    videoId := "videoId_example" // string | Unique identifier of the chosen video 
    file := os.NewFile(1234, "some_file") // *os.File | The image to be added as a thumbnail.


    res, err := client.Videos.UploadThumbnailFile(videoId, file)

    // you can also use a Reader instead of a File:
    // client.Videos.UploadThumbnail(videoId, fileName, fileReader)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Videos.UploadThumbnail``: %v\
", err)
    }
    // response from `UploadThumbnail`: Video
    fmt.Fprintf(os.Stdout, "Response from `Videos.UploadThumbnail`: %v\
", res)
}

Responses

ExamplesSchema

Success

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "createdAt": "2020-03-03T12:52:03.085Z",
  "publishedAt": "2020-07-14T23:36:18.598Z",
  "source": {
    "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
  },
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27",
    "hls": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8",
    "thumbnail": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg",
    "mp4": "https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/mp4/source.mp4"
  }
}