Sign up for free
  • VOD

Videos

get

List all video objects

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

titlestring

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

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\"]"
metadataobject

Videos can be tagged with metadata tags in key:value pairs. You can search for videos with specific key value pairs using this parameter.

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

Retrieve video objects by description.

Example
"New Zealand"
liveStreamIdstring

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

Example
"li400mYKSgQ6xs7taUeSaEKr"
sortBystring

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"
sortOrderstring

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"
currentPageint

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

Default
1
Example
2
pageSizeint

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

Default
25
Example
30

Responses

Request examples

<?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']]);

Response examples

Success

{
  "data": [
    {
      "videoId": "vi4blUQJFrYWbaG44NChkH27",
      "playerId": "pl45KFKdlddgk654dspkze",
      "title": "Maths video",
      "description": "An amazing video explaining the string theory",
      "language": "en",
      "languageOrigin": "api",
      "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+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": false,
      "discardedAt": null,
      "deletesAt": null,
      "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.",
      "language": "en",
      "languageOrigin": "api",
      "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+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": false,
      "discardedAt": null,
      "deletesAt": null,
      "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.",
      "language": "fr",
      "languageOrigin": "api",
      "public": false,
      "panoramic": false,
      "mp4Support": true,
      "tags": [
        "General",
        "Videos"
      ],
      "metadata": [
        {
          "key": "Length",
          "value": "Short"
        }
      ],
      "publishedAt": "2019-12-16T08:25:51+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": false,
      "discardedAt": null,
      "deletesAt": null,
      "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"
      }
    ]
  }
}
post

Create a video object

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

titlestring

required

The title of your new video.

Example
"Maths video"
descriptionstring

A brief description of your video.

Example
"A video about string theory."
sourcestring

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"
publicboolean

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

Default
true
Example
true
panoramicboolean

Indicates if your video is a 360/immersive video.

Default
false
Example
false
mp4Supportboolean

Enables mp4 version in addition to streamed version.

Default
true
Example
true
playerIdstring

The unique identification number for your video player.

Example
"pl45KFKdlddgk654dspkze"
tagsarray

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

Example
"[\"maths\", \"string theory\", \"video\"]"
metadataarray

A list of key value pairs that you use to provide metadata for your video.

Example
"[{\"key\": \"Author\", \"value\": \"John Doe\"}]"
keystring

The constant that defines the data set.

Example
"Color"
valuestring

A variable which belongs to the data set.

Example
"Green"
clipobject (video-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.
startTimecodestring

The timestamp that defines the beginning of the video clip you want to create. The value must follow the HH:MM:SS format.

Pattern
^(?:\d{2,3}:[0-5]\d:[0-5]\d(?:\.\d{1,3}|\:\d{1,2})?|\d{1,7})$
Example
"00:01:15"
endTimecodestring

The timestamp that defines the end of the video clip you want to create. The value must follow the HH:MM:SS format.

Pattern
^(?:\d{2,3}:[0-5]\d:[0-5]\d(?:\.\d{1,3}|\:\d{1,2})?|\d{1,7})$
Example
"00:02:33"
watermarkobject (video-watermark)
idstring

id of the watermark

Example
"watermark_1BWr2L5MTQwxGkuxKjzh6i"
topstring

Distance expressed in px or % between the top-border of the video and the watermark-image.

Example
"10px"
leftstring

Distance expressed in px or % between the left-border of the video and the watermark-image.

Example
"10px"
bottomstring

Distance expressed in px or % between the bottom-border of the video and the watermark-image.

Example
"10px"
rightstring

Distance expressed in px or % between the right-border of the video and the watermark-image.

Example
"10px"
widthstring

Width of the watermark-image relative to the video if expressed in %. Otherwise a fixed width. NOTE: To keep intrinsic watermark-image width use initial.

Example
"initial"
heightstring

Height of the watermark-image relative to the video if expressed in %. Otherwise a fixed height. NOTE: To keep intrinsic watermark-image height use initial.

Example
"initial"
opacitystring

Opacity expressed in % only to specify the degree of the watermark-image transparency with the video.

Example
"70%"
languagestring or null

Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the IETF language tag format.

language is a permanent attribute of the video. You can update it to another language using the PATCH /videos/{videoId} operation. This triggers the API to generate a new transcript using a different language.

Enum
  • ar
  • ca
  • cs
  • da
  • de
  • el
  • en
  • es
  • fa
  • fi
  • fr
  • he
  • hi
  • hr
  • hu
  • it
  • ja
  • ko
  • ml
  • nl
  • nn
  • no
  • pl
  • pt
  • ru
  • sk
  • sl
  • te
  • tr
  • uk
  • ur
  • vi
  • zh
Example
"fr"
transcriptboolean

Use this parameter to enable transcription.

  • When true, the API generates a transcript for the video.
  • The default value is false.
  • If you define a video language using the language parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video.
  • When the API generates a transcript, it will be available as a caption for the video.
transcriptSummaryboolean

Use this parameter to enable summarization. We recommend using this parameter together with transcript: true.

  • When true, the API generates a summary for the video, based on the transcription.
  • The default value is false.
  • If you define a video language using the language parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video.
transcriptSummaryAttributesarray

Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. The possible values are abstract and takeaways.

Responses

Request examples

{
  "title": "Maths video",
  "description": "An amazing video explaining string theory.",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "playerId": "pl45KFKdlddgk654dspkze",
  "language": "en",
  "transcript": true,
  "transcriptSummary": true,
  "transcriptSummaryAttributes": [
    "abstract",
    "takeaways"
  ],
  "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%"
  }
}

Response examples

Created

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory",
  "language": "en",
  "languageOrigin": "api",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "playerId": "pl4k0jvEUuaTdRAEjQ4Jfrgz",
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "publishedAt": "2024-07-14T23:36:07+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
post

Upload a video

Ingest a video from a source or file.

filefile

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"

Responses

Request examples

// 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)
    }
      }

Response examples

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": "2024-07-14T23:36:07+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
post

Upload a thumbnail

Upload a thumbnail for a certain video.

filefile

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.

Responses

Request examples

// 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)
}

Response examples

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+00:00",
  "publishedAt": "2020-07-14T23:36:07+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
patch

Set a thumbnail

Set a thumbnail from a specific time interval within a video.

timecodestring

required

Frame in video to be used as a placeholder before the video plays. Example: '"00:01:00.000" for 1 minute into the video.' Valid Patterns: "hh:mm:ss.ms" "hh:mm:ss:frameNumber" "124" (integer value is reported as seconds) If selection is out of range, "00:00:00.00" will be chosen.

Pattern
\d{2}:\d{2}:\d{2}(\.\d{2})?

Responses

Request examples

{
  "timecode": "00:00:00.000"
}

Response examples

Success

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining string theory",
  "public": false,
  "panoramic": false,
  "mp4Support": true,
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "publishedAt": "2024-07-14T23:36:07+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
get

Retrieve a video object

Retrieve the video details by video id.

videoIdstring

required

The unique identifier for the video you want details about.

Responses

Request examples

// 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#get

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 | The unique identifier for the video you want details about.

    
    res, err := client.Videos.Get(videoId)

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

Response examples

Success

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining string theory",
  "language": "en",
  "languageOrigin": "api",
  "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+00:00",
  "updatedAt": "2019-12-16T08:48:49+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
delete

Delete a video object

Delete a video object by video ID.

By default, deleted videos cannot be recovered. If you have the Video Restore feature enabled, this operation will discard the video instead of permanently deleting it. Make sure you subscribe to the Video Restore feature if you want to be able to restore deleted videos!

The Video Restore feature retains videos for 90 days, after which the videos are permanently deleted.

videoIdstring

required

The video ID for the video you want to delete.

Example
"vi4k0jvEUuaTdRAEjQ4Jfrgz"

Responses

Request examples

// 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#delete

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 | The video ID for the video you want to delete.
    err := client.Videos.Delete(videoId)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Videos.Delete``: %v\
", err)
    }
}

Response examples

No Content

Empty response

patch

Update a video object

Update the parameters associated with a video ID.

playerIdstring

The unique ID for the player you want to associate with your video.

Example
"pl4k0jvEUuaTdRAEjQ4Jfrgz"
titlestring

The title you want to use for your video.

descriptionstring

A brief description of the video.

Example
"A film about good books."
publicboolean

Whether the video is publicly available or not. False means it is set to private. Default is true. Tutorials on private videos.

Example
true
panoramicboolean

Whether the video is a 360 degree or immersive video.

Example
false
mp4Supportboolean

Whether the player supports the mp4 format.

Example
true
tagsarray

A list of terms or words you want to tag the video with. Make sure the list includes all the tags you want as whatever you send in this list will overwrite the existing list for the video.

Example
"[\"maths\", \"string theory\", \"video\"]"
metadataarray

A list (array) of dictionaries where each dictionary contains a key value pair that describes the video. As with tags, you must send the complete list of metadata you want as whatever you send here will overwrite the existing metadata for the video.

keystring

The constant that defines the data set.

Example
"Color"
valuestring

A variable which belongs to the data set.

Example
"Green"
languagestring or null

Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the IETF language tag format.

language is a permanent attribute of the video. You can update it to another language using the PATCH /videos/{videoId} operation. This triggers the API to generate a new transcript using a different language.

Enum
  • ar
  • ca
  • cs
  • da
  • de
  • el
  • en
  • es
  • fa
  • fi
  • fr
  • he
  • hi
  • hr
  • hu
  • it
  • ja
  • ko
  • ml
  • nl
  • nn
  • no
  • pl
  • pt
  • ru
  • sk
  • sl
  • te
  • tr
  • uk
  • ur
  • vi
  • zh
Example
"fr"
transcriptboolean

Use this parameter to enable transcription.

  • When true, the API generates a transcript for the video.
  • The default value is false.
  • If you define a video language using the language parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video.
  • When the API generates a transcript, it will be available as a caption for the video.
transcriptSummaryboolean

Use this parameter to enable summarization.

  • When true, the API generates a summary for the video, based on the transcription.
  • The default value is false.
  • If you define a video language using the language parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video.
transcriptSummaryAttributesarray

Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. The possible values are abstract and takeaways.

Responses

Request examples

{
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "String theory",
  "description": "An amazing video explaining the string theory",
  "public": false,
  "language": "en",
  "transcript": true,
  "transcriptSummary": true,
  "transcriptSummaryAttributes": [
    "abstract",
    "takeaways"
  ],
  "panoramic": false,
  "mp4Support": true,
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ]
}

Response examples

Success

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory",
  "language": "en",
  "languageOrigin": "api",
  "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+00:00",
  "updatedAt": "2019-12-16T08:48:49+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "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"
  }
}
get

List all discarded video objects

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

titlestring

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

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\"]"
metadataobject

Videos can be tagged with metadata tags in key:value pairs. You can search for videos with specific key value pairs using this parameter.

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

Retrieve video objects by description.

Example
"New Zealand"
liveStreamIdstring

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

Example
"li400mYKSgQ6xs7taUeSaEKr"
sortBystring

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"
sortOrderstring

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"
currentPageint

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

Default
1
Example
2
pageSizeint

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

Default
25
Example
30

Responses

Response examples

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+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": true,
      "discardedAt": "2024-10-16T08:48:49+00:00",
      "deletesAt": "2024-11-16T08:48:49+00:00",
      "source": {
        "uri": "/videos/c188ed58-3403-46a2-b91b-44603d10b2c9/source"
      },
      "assets": null
    },
    {
      "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+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": true,
      "discardedAt": "2024-10-16T08:48:49+00:00",
      "deletesAt": "2024-11-16T08:48:49+00:00",
      "source": {
        "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
      },
      "assets": null
    },
    {
      "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+00:00",
      "updatedAt": "2019-12-16T08:48:49+00:00",
      "discarded": true,
      "discardedAt": "2024-10-16T08:48:49+00:00",
      "deletesAt": "2024-11-16T08:48:49+00:00",
      "source": {
        "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
      },
      "assets": null
    }
  ],
  "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"
      }
    ]
  }
}
get

Retrieve a discarded video object

Retrieve the video details of a discarded video object by video id.

videoIdstring

required

The unique identifier for the video you want details about.

Responses

Response examples

Success

{
  "videoId": "vi4blUQJFrYWbaG44NChkH27",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining 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+00:00",
  "updatedAt": "2019-12-16T08:48:49+00:00",
  "discarded": true,
  "discardedAt": "2024-10-16T08:48:49+00:00",
  "deletesAt": "2024-11-16T08:48:49+00:00",
  "source": {
    "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
  },
  "assets": null
}
patch

Update a discarded video object

Restore a discarded video

discardedboolean

Use this parameter to restore a discarded video when you have the Video Restore feature enabled. This parameter only accepts false as a value!

Responses

Request examples

{
  "discarded": false
}

Response examples

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"
    }
  ],
  "publishedAt": "2019-12-16T08:25:51+00:00",
  "updatedAt": "2019-12-16T08:48:49+00:00",
  "discarded": true,
  "discardedAt": "2024-10-16T08:48:49+00:00",
  "deletesAt": "2024-11-16T08:48:49+00:00",
  "source": {
    "uri": "/videos/vi4blUQJFrYWbaG44NChkH27/source"
  },
  "assets": null
}
get

Retrieve video status and details

Retrieve upload status and 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.

videoIdstring

required

The unique identifier for the video you want the status for.

Example
"vi4k0jvEUuaTdRAEjQ4Jfrgz"

Responses

Request examples

// 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#getStatus

 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 | The unique identifier for the video you want the status for.

    
    res, err := client.Videos.GetStatus(videoId)

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

Response examples

Success

{
  "ingest": {
    "status": "uploaded",
    "filesize": 273579401,
    "receivedBytes": [
      {
        "to": 134217727,
        "from": 0,
        "total": 273579401
      },
      {
        "to": 268435455,
        "from": 134217728,
        "total": 273579401
      },
      {
        "to": 273579400,
        "from": 268435456,
        "total": 273579401
      }
    ]
  },
  "encoding": {
    "playable": true,
    "qualities": [
      {
        "quality": "360p",
        "status": "encoded"
      },
      {
        "quality": "480p",
        "status": "encoded"
      },
      {
        "quality": "720p",
        "status": "encoded"
      },
      {
        "quality": "1080p",
        "status": "encoding"
      },
      {
        "quality": "2160p",
        "status": "waiting"
      }
    ],
    "metadata": {
      "width": 424,
      "height": 240,
      "bitrate": 411.218,
      "duration": 4176,
      "framerate": 24,
      "samplerate": 48000,
      "videoCodec": "h264",
      "audioCodec": "aac",
      "aspectRatio": "16/9"
    }
  }
}
post

Upload with an delegated upload token

Uploading a video with the delegated upload token.

filefile

required

The path to the video you want to upload.

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

The video id returned by the first call to this endpoint in a large video upload scenario.

Responses

Request examples

// 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#uploadWithUploadToken

Response examples

Created

{
  "videoId": "vi4k0jvEUuaTdRAEjQ4Jfrgz",
  "playerId": "pl45KFKdlddgk654dspkze",
  "title": "Maths video",
  "description": "An amazing video explaining the string theory",
  "language": "en",
  "languageOrigin": "api",
  "public": false,
  "panoramic": false,
  "tags": [
    "maths",
    "string theory",
    "video"
  ],
  "metadata": [
    {
      "key": "Author",
      "value": "John Doe"
    },
    {
      "key": "Format",
      "value": "Tutorial"
    }
  ],
  "publishedAt": "2024-07-14T23:36:07+00:00",
  "discarded": false,
  "discardedAt": null,
  "deletesAt": null,
  "source": {
    "uri": "/videos/vi4k0jvEUuaTdRAEjQ4Jfrgz/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"
  }
}

Was this page helpful?