The vzaar Developer Hub

Welcome to the vzaar developer hub. You'll find comprehensive guides and documentation to help you start working with vzaar as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Official Libraries

 
Library
Current Version
Source Code

PHP

2.0.0

Ruby

2.0.0

Java

2.0.4

.NET

2.0.0

Swift (iOS)

2.0.0

Android

2.0.0

List Videos

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/videos
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/videos"
# iterate over all videos
VzaarApi::Video.each_item do |video|
  puts video.title
end

# paginate videos
pager = VzaarApi::Video.paginate
pager.first.each do |video|
  puts video.title
end
<?php

// Iterate over all videos
foreach (VzaarApi\VideosList::each_item() as $video) {
  echo 'Video: ' . $video->id . PHP_EOL;
}

// Paginate videos
$params = ['per_page' => '2'];
$pager  = VzaarApi\VideosList::paginate($params);

foreach ($pager as $video) {
  echo 'Video: ' . $video->id . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 123,
      "title": "My Video",
      "description": "Video Description goes here",
      "state": "ready",
      "private": false,
      "user_id": 42,
      "user_login": "my-login",
      "account_id": 101,
      "account_name": "my-account",
      "duration": 1050,
      "created_at": "2018-01-17T15:48:44.000Z",
      "updated_at": "2018-01-17T18:02:06.000Z",
      "url": "https://vzaar.com/videos/123",
      "seo_url": null,
      "asset_url": "https://view.vzaar.com/123/video",
      "poster_url": "https://view.vzaar.com/123/image",
      "thumbnail_url": "https://view.vzaar.com/123/thumb",
      "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
      "tag" : [ "My Tag", "Tagged Again" ],
      "categories": [
        {
          "id": 1,
          "account_id": 1,
          "user_id": 1,
          "name": "Sciences",
          "description": null,
          "parent_id": null,
          "depth": 0,
          "node_children_count": 3,
          "tree_children_count": 5,
          "node_video_count": 3,
          "tree_video_count": 6,
          "created_at": "2015-04-06T22:03:24.000Z",
          "updated_at": "2016-01-06T12:08:38.000Z"
        }
      ],
      "adverts": [
         {
           "advert_id": 1,
           "name": "Single skippable inline (test)",
           "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=",
           "position": "mid",
           "time": "00:00:30",
           "placement_scope": "user",
           "created_at": "2017-09-06T21:20:27.000Z",
           "updated_at": "2017-09-06T21:20:27.000Z"
         }
      ],
      "renditions": [
        {
          "id": 66,
          "code": "magic",
          "width": 416,
          "height": 258,
          "bitrate": 200,
          "framerate": "12.0",
          "status": "finished",
          "size_in_bytes": 12345,
          "url": "https://view.vzaar.com/123/download/magic"
        }
      ],
      "legacy_renditions": [
        {
          "id": 10567122,
          "type": "standard",
          "width": 448,
          "height": 278,
          "bitrate": 512,
          "status": "Finished"
        }
      ],
      "subtitles: [
        "id": 123,
        "language": "English",
        "code": "en",
        "title": "123-en.srt",
        "url": "https://view.vzaar.com/subtitles/123",
        "created_at": "2018-10-01T10:13:41.000Z",
        "updated_at": "2018-10-01T10:13:41.000Z"
      ]
    }
  ],
  "meta": {
    "total_count": 212,
    "links": {
      "first": "https://api.vzaar.com/api/v2/videos?order=asc&page=1&state=ready",
      "next": "https://api.vzaar.com/api/v2/videos?order=asc&page=2&state=ready",
      "previous": null,
      "last": "https://api.vzaar.com/api/v2/videos?order=asc&page=9&state=ready"
    }
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Query Params

q
string

Search query

sort
string

Video attribute to sort results with. Acceptable values are: id, title, created_at

order
string

Specify sort order. Acceptable values are: asc, desc

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result. Maximum value is 100

tag
string

Tag for filtered results

category_id
int32

Category for filtered results

categorized
boolean

Filter videos on whether they are categorized or not

state
string

Video state for filtered results. Acceptable values are: processing, ready, failed

 

Looking for processing / failed videos?

By default, only videos in a ready state are returned in the video list. Any videos that are busy processing or have failed during processing are excluded from the video list. You can however still retrieve these videos by filtering on the video state:

https://app.vzaar.com/api/v2/videos?state=failed

Lookup Video

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/videos/id
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/videos/42"
video = VzaarApi::Video.find(42)
puts video.id
=> 42
<?php

$video = VzaarApi\Video::find(123);
echo 'Video: ' . $video->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Video",
    "description": "Video Description goes here",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "tag" : [ "My Tag", "Tagged Again" ],
    "categories": [
      {
        "id": 1,
        "account_id": 1,
        "user_id": 1,
        "name": "Sciences",
        "description": null,
        "parent_id": null,
        "depth": 0,
        "node_children_count": 3,
        "tree_children_count": 5,
        "node_video_count": 3,
        "tree_video_count": 6,
        "created_at": "2015-04-06T22:03:24.000Z",
        "updated_at": "2016-01-06T12:08:38.000Z"
      }
    ],
      "adverts": [
         {
           "advert_id": 1,
           "name": "Single skippable inline (test)",
           "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=",
           "position": "mid",
           "time": "00:00:30",
           "placement_scope": "user",
           "created_at": "2017-09-06T21:20:27.000Z",
           "updated_at": "2017-09-06T21:20:27.000Z"
         }
      ],
    "renditions": [
      {
        "id": 66,
        "code": "magic",
        "width": 416,
        "height": 258,
        "bitrate": 200,
        "framerate": "12.0",
        "status": "finished",
        "size_in_bytes": 12345,
        "url": "https://view.vzaar.com/123/download/magic"
      }
    ],
    "legacy_renditions": [
      {
        "id": 10567122,
        "type": "standard",
        "width": 448,
        "height": 278,
        "bitrate": 512,
        "status": "Finished"
      }
    ],
    "subtitles: [
      "id": 123,
      "language": "English",
      "code": "en",
      "title": "123-en.srt",
      "url": "https://view.vzaar.com/subtitles/123",
      "created_at": "2018-10-01T10:13:41.000Z",
      "updated_at": "2018-10-01T10:13:41.000Z"
    ]
  }
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

 

State

A video can have multiple states depending on whether the video is being processed, ready for playback or failed processing. The possible values for state are:

  • processing: Your video is being processed and is not yet ready for playback.
  • ready: At least one rendition has been successfully processed and your video is ready for playback. Note that other renditions may still be processing.
  • failed: We could not successfully process your video and it will not playback.

Renditions vs Legacy renditions

When you create a new video, one or more renditions are created for your video. A rendition is an encoded mp4 video file which is created using a specified encoding preset. Each rendition will have different quality settings allowing vzaar to deliver the best possible playback across different platforms and devices. Encoding presets are configured in your ingest recipe.

A legacy rendition is an encoded mp4 video file that was created by our legacy video encoder.

Create Video

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/videos
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "guid": "<provided-in-signature>",
       "title": "My Video"
     }' "https://api.vzaar.com/api/v2/videos"
# from local file
video = VzaarApi::Video.create(path: 'path/to/video.mp4', title: 'my-video')
puts video.title
=> "my-video"

# using url
video = VzaarApi::Video.create(url: 'http://example.com/video.mp4', title: 'my-video')
puts video.title
=> "my-video"
<?php

// From local file
$params = [
  'title'    => 'Test Video 7.2MB',
  'filepath' => './videos/medium.mp4',
];
$video = VzaarApi\Video::create($params);
echo 'Video: ' . $video->id;

// From URL
$params = [
  'title' => 'Test Video 7.2MB',
  'url'   => 'http://example.com/video.mp4',
];
$video = VzaarApi\Video::create($params);
echo 'Video: ' . $video->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Video",
    "description": "Video Description goes here",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "categories": [],
    "adverts": [],
    "renditions": [],
    "subtitles: []
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "guid is missing"
    }
  ]
}

Body Params

guid
string
required

Provided in signature

ingest_recipe_id
int32

Specify if you do not want to use your default Ingest Recipe

title
string

Video title. If not provided this will default to your source filename

description
string

Video description

 

Upload Signatures

Before creating a video you must first generate an upload signature and upload your source video. The upload signature allows you to upload directly to the vzaar upload bucket on AWS S3. Once your video has been successfully uploaded, you can then proceed with video creation.

Unless you are implementing your own custom upload process, this should be handled by the official client library of your choice.

For more information about upload signatures, please refer to the Upload Signatures documentation.

Replace Video

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/videos/id/replace
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "guid": "<provided-in-signature>",
       "title": "My Video"
     }' "https://api.vzaar.com/api/v2/videos/<video_id>/replace"
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Video",
    "description": "Video Description goes here",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "categories": [],
    "adverts": [],
    "renditions": [],
    "subtitles": []
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "guid is missing"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

Body Params

guid
string
required

Provided in signature

ingest_recipe_id
int32

Specify if you do not want to use your default Ingest Recipe

title
string

Video title. If not provided this will default to your source filename

description
string

Video description

 

Upload Signatures

Before creating a video you must first generate an upload signature and upload your source video. The upload signature allows you to upload directly to the vzaar upload bucket on AWS S3. Once your video has been successfully uploaded, you can then proceed with video creation.

Unless you are implementing your own custom upload process, this should be handled by the official client library of your choice.

For more information about upload signatures, please refer to the Upload Signatures documentation.

Update Video

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/videos/id
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "title": "My Updated Video",
       "description": "This is my updated video",
     }' "https://api.vzaar.com/api/v2/videos/1"
video = VzaarApi::Video.find(42)
video.title = 'the new title'
video.description = 'the new description'
video.private = false
video.save
<?php

$video = VzaarApi\Video::find(42);

$video->title       = 'New Title';
$video->description = 'New Description';

if ($video->edited()) {
  $video->save();
}
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Updated Video",
    "description": "This is my updated video",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "categories": [],
    "adverts": [],
    "renditions": [],
    "subtitles": []
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "Found unpermitted parameters: user_id"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

Body Params

title
string

Video title — if not provided this will default to your source filename

description
string

Video description

private
boolean

Private videos cannot be publicly viewed on vzaar.com

seo_url
string

URL for SEO purposes

category_ids
array of integers

List of category id values to associate with this video

tags
string

Tags to associate with this video

 

Upload Signatures

Before creating a video you must first generate an upload signature and upload your source video. The upload signature allows you to upload directly to the vzaar upload bucket on AWS S3. Once your video has been successfully uploaded, you can then proceed with video creation.

Unless you are implementing your own custom upload process, this should be handled by the official client library of your choice.

For more information about upload signatures, please refer to the Upload Signatures documentation.

Video Categorisation

The ability to categorise a video is only available via PATCH requests. When categorising a video, please take note of the following three scenarios:

  1. If you do not specify the category_ids parameter, any existing categorisation will remain untouched.
  2. If you specify an empty array for category_ids all existing categorisation will be lost i.e. you are specifying that your video should be in no categories.
  3. If you provide one or more category id values for category_ids your video will be categorised to match your provided values i.e. all previous categorisation is removed and the video is recategorised based on the values you provide.

Delete Video

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vzaar.com/api/v2/videos/id
curl -X DELETE \
     -H "X-Client-Id: <client-id>" \
     -H "X-Auth-Token: <auth-token>" \
     "https://api.vzaar.com/api/v2/videos/1"
video = VzaarApi::Video.find(42)
video.delete
<?php

$video = VzaarApi\Video::find(42);
$video->delete();
A binary file was returned

You couldn't be authenticated

{ 
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

 

Create Multipart

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/signature/multipart/2
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "filename": "video.mp4",
       "filesize": 52428800,
       "uploader": "Ruby 2.3"
     }' "https://api.vzaar.com/api/v2/signature/multipart/2"
# using the Multipart class
options = { filename: 'video.mp4', filesize: 10000000 }
VzaarApi::Signature::Multipart.create options

# using the Factory class
options = { path: './path/to/video.mp4' }
VzaarApi::Signature::Factory.create options
<?php

$path = './videos/medium.mp4';

$multi = [
  'filename' => basename($path),
  'filesize' => filesize($path),
];

$signature = VzaarApi\Signature::multipart($multi);

echo 'guid: ' . $signature->guid . PHP_EOL;
echo 'parts: ' . $signature->parts . PHP_EOL;
echo 'part_size_in_bytes: ' . $signature->part_size_in_bytes . PHP_EOL;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "x-amz-credential": "AKIAJ74MFWNVAFH6P7FQ/20181101/us-east-1/s3/aws4_request",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-date": "20181101T151558Z",
    "x-amz-signature": "<signature-string>",
    "key": "vzaar/th2/Z_1/source/th2Z_17QvJwE/${filename}",
    "acl": "private",
    "policy": "<signed-policy-string>",
    "success_action_status": "201",
    "guid": "<guid>",
    "bucket": "vzaar-upload",
    "upload_hostname": "https://vzaar-upload.s3.amazonaws.com",
    "part_size": "6MB",
    "part_size_in_bytes": 6291456,
    "parts": 1
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "filename is missing, filesize is missing, uploader is missing"
    }
  ]
}

Body Params

filename
string
required

base name of your video file

filesize
int64
required

size in bytes of your video file

uploader
string
required

uploader description used for metadata, analytics and support

desired_part_size
string

desired part size specified as a string

 

This signature is required for a multi-part file upload. Typically this would be for larger files. The size of your file MUST be at least 5MB. If your file does not meet this minimum size limitation then you will receive an error response when requesting the signature.

The signature will provide a part_size which specifies the size of each uploaded part. Only the final part uploaded can be smaller than the specified part_size. This MUST be respected or your video will either fail during processing (if you upload fewer parts than expected), or your video will be missing some of the original source (if you upload more parts than expected).

The default part_size is currently 16MB, but this is subject to change. Please contact support if you want your default changed.

For more information about multipart uploads and S3, please see the AWS documentation

Desired Part Size

If you do not provide a desired part size, vzaar will determine the best part size for you to use based on your file size. If your file size is less than the default part size, you will be provided with the part size to use.

If you specify a desired part size, this will be validated. The signature will contain either your desired part size if you provided a valid value, or in the case that your desired part size is invalid, a valid part size will be provided.

You MUST specify a desired part size in MB.

Create Single

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/signature/single/2
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "uploader": "Ruby 2.3"
     }' "https://api.vzaar.com/api/v2/signature/single/2"
# using the Multipart class
VzaarApi::Signature::Single.create

# using the Factory class
options = { path: './path/to/video.mp4' }
VzaarApi::Signature::Factory.create options
<?php

$signature = VzaarApi\Signature::single([]);
echo 'guid: '. $signature->guid;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "x-amz-credential": "AKIAJ74MFWNVAFH6P7FQ/20181101/us-east-1/s3/aws4_request",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-date": "20181101T151558Z",
    "x-amz-signature": "<signature-string>",
    "key": "vzaar/th2/Z_1/source/th2Z_17QvJwE/${filename}",
    "acl": "private",
    "policy": "<signed-policy-string>",
    "success_action_status": "201",
    "guid": "<guid>",
    "bucket": "vzaar-upload",
    "upload_hostname": "https://vzaar-upload.s3.amazonaws.com",
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "Filesize cannot exceed 5GB"
    }
  ]
}

Body Params

uploader
string
required

uploader description used for metadata, analytics and support

filename
string

base name of your video file

filesize
int64

size in bytes of your video file

 

This signature is required for a single-part file upload. Typically this would be for smaller files or simpler file upload implementations e.g. html form post.

You can also send the optional filesize parameter, and if provided vzaar will validate that your file is an acceptable size. The maximum allowed file size for this signature is 5GB. If your file size exceeds 5GB then you must perform a multipart upload.

List Categories

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/categories
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/categories"
# iterate over all categories
VzaarApi::Category.each_item do |category|
  puts category.name
end

# paginate categories
pager = VzaarApi::Category.paginate
pager.first.each do |video|
  puts category.name
end
<?php

// Iterate over all Categories
foreach (VzaarApi\CategoriesList::each_item() as $category) {
  echo 'Category: ' . $category->name . PHP_EOL;
}

// Paginate Categories
$params = ['per_page' => '2'];
$pager  = VzaarApi\CategoriesList::paginate($params);

foreach ($pager as $category) {
  echo 'Category: ' . $category->name . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 1,
      "account_id": 1,
      "user_id": 1,
      "name": "Sciences",
      "description": null,
      "parent_id": null,
      "depth": 0,
      "node_children_count": 3,
      "tree_children_count": 5,
      "node_video_count": 3,
      "tree_video_count": 6,
      "created_at": "2015-04-06T22:03:24.000Z",
      "updated_at": "2016-01-06T12:08:38.000Z"
    },
    {
      "id": 2,
      "account_id": 1,
      "user_id": 1,
      "name": "Chemistry",
      "description": null,
      "parent_id": 1,
      "depth": 0,
      "node_children_count": 3,
      "tree_children_count": 5,
      "node_video_count": 3,
      "tree_video_count": 6,
      "created_at": "2015-04-06T22:03:24.000Z",
      "updated_at": "2016-01-06T12:08:38.000Z"
    }
  ],
  "meta": {
    "links": {
      "first": "http://api.vzaar.com/api/v2/categories?page=1",
      "last": "http://api.vzaar.com/api/v2/categories?page=4",
      "next": "http://api.vzaar.com/api/v2/categories?page=2",
      "previous": null
    },
    "total_count": 4
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Query Params

sort
string

Video attribute to sort results with. Acceptable values are: id, name

order
string

Specify sort order. Acceptable values are: asc / desc

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result — maximum value is 50

levels
int32

Number of hierarchy levels to include — this is one-based so a value of 2 would return your root categories and only their immediate child categories

ids
array of integers

List of category id values to allow granular control of result list

 

Listing Categories

Listing categories will page through all your categories, returning every category you have created regardless of the parent category or category depth i.e. this allows you to retrieve your entire collection of categories through paged results.

List Category Subtree

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/categories/id/subtree
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/categories/42/subtree"
pager = VzaarApi::Category.find(42).subtree

# iterate over all categories in subtree
pager.each_item do |category|
  puts category.name
end

# paginate subtree categories
pager.first.each do |video|
  puts category.name
end
<?php

$parent = VzaarApi\Category::find(42);

foreach ($parent->subtree() as $category) {
  echo 'Category: ' . $category->name . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 42,
      "account_id": 1,
      "user_id": 1,
      "name": "Biology",
      "description": null,
      "parent_id": 1,
      "depth": 0,
      "node_children_count": 3,
      "tree_children_count": 5,
      "node_video_count": 3,
      "tree_video_count": 6,
      "created_at": "2015-04-06T22:03:24.000Z",
      "updated_at": "2016-01-06T12:08:38.000Z"
    },
    {
      "id": 2,
      "account_id": 1,
      "user_id": 1,
      "name": "Chemistry",
      "description": null,
      "parent_id": 42,
      "depth": 0,
      "node_children_count": 3,
      "tree_children_count": 5,
      "node_video_count": 3,
      "tree_video_count": 6,
      "created_at": "2015-04-06T22:03:24.000Z",
      "updated_at": "2016-01-06T12:08:38.000Z"
    }
  ],
  "meta": {
    "links": {
      "first": "http://api.vzaar.com/api/v2/categories/42/subtree?page=1",
      "last": "http://api.vzaar.com/api/v2/categories/42/subtree?page=4",
      "next": "http://api.vzaar.com/api/v2/categories/42/subtree?page=2",
      "previous": null
    },
    "total_count": 4
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Category ID

Query Params

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result. Maximum value is 50

levels
int32

Number of hierarchy levels to include — this is one-based so a value of 2 would return the category matching the request id and any immediate child categories

 

Listing Category Subtree

Listing a category's subtree will always include the category itself, plus any descendants that may exist.

Lookup Category

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/categories/id
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/categories/42"
category = VzaarApi::Category.find(42)
puts category.id
=> 42
<?php

$category = VzaarApi\Category::find(42);
echo 'Category: ' . $category->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "account_id": 1,
    "user_id": 1,
    "name": "Sciences",
    "description": null,
    "parent_id": null,
    "depth": 0,
    "node_children_count": 3,
    "tree_children_count": 5,
    "node_video_count": 3,
    "tree_video_count": 6,
    "created_at": "2015-04-06T22:03:24.000Z",
    "updated_at": "2016-01-06T12:08:38.000Z"
  }
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Category ID

 

Reference

Property
Description

parent_id

This is the id of this category's parent category.

node_children_count

The number of categories that have this category as their parent i.e. one level below this category in the hierarchy.

tree_children_count

The number of categories that have this category as an ancestor i.e. any level below this category in the hierarchy.

node_video_count

The number of videos in categories that have this category as their parent.

tree_video_count

The number of videos in categories that have this category as an ancestor.

Create Category

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/categories
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "My category"
     }' 
     "https://api.vzaar.com/api/v2/categories"
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -d '{
       "name": <name>,
       "parent_id": <category_id>
     }' "https://api.vzaar.com/api/v2/ingest_recipes"
# top-level category
VzaarApi::Category.create(name: 'category test')

# subcategory
VzaarApi::Category.create(name: 'category test', parent_id: 42)
<?php

// Top-level Category
VzaarApi\Category::create(['name' => 'My Category']);

// Sub-Category
VzaarApi\Category::create([
  'name'      => 'My Sub-Category',
  'parent_id' => 42,
]);
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 3495,
    "account_id": 42,
    "user_id": 42,
    "name": "category name",
    "parent_id": null,
    "depth": 0,
    "node_children_count": 0,
    "tree_children_count": 0,
    "node_video_count": 0,
    "tree_video_count": 0,
    "created_at": "2017-01-23T17:41:35.000Z",
    "updated_at": "2017-01-23T17:41:35.000Z"
  }
}

Body Params

name
string
required
parent_id
int32

Id of the parent Category — omit to create a top-level Category

 

Update Category

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/categories/id
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "title": "New category name",
       "parent_id": 12,
     }' "https://api.vzaar.com/api/v2/categories/1"
cat = VzaarApi::Category.find(1)

# rename and move to new parent
cat.name = "new name"
cat.parent_id = 42
cat.save

# or move to root
cat.move_to_root = true
cat.save
<?php

$category = VzaarApi\Category::find(42);

// Rename and move to new parent
$category->name = "My Updated Category";
$category->parent_id = 101;
$category->save();

// ...or move to root
$category->move_to_root = true;
$category->save();
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1234,
    "account_id": 42,
    "user_id": 42,
    "name": "changed",
    "description": null,
    "parent_id": null,
    "depth": 0,
    "node_children_count": 0,
    "tree_children_count": 0,
    "node_video_count": 3,
    "tree_video_count": 3,
    "created_at": "2015-10-09T10:44:31.000Z",
    "updated_at": "2017-01-31T10:37:20.000Z"
  }
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Category ID

Body Params

name
string

Rename the category

parent_id
int32

Move the category underneath an existing parent node

move_to_root
boolean

Move the category to the top level — can not be used in combination with parent_id

 

Delete Category

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vzaar.com/api/v2/categories/id
curl -X DELETE \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/categories/1"
category = VzaarApi::Category.find(1)

category.delete
<?php

$category = VzaarApi\Category::find(42);
$category->delete();
A binary file was returned

You couldn't be authenticated

{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Category ID

 

Note

Deleting a category will also delete any children

List Playlists

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/feeds/playlists
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/feeds/playlists"
# iterate over all playlists
VzaarApi::Playlist.each_item do |playlist|
  puts playlist.title
end

# paginate playlists
pager = VzaarApi::Playlist.paginate
pager.first.each do |playlist|
  puts playlist.title
end
<?php

// Iterate over all Playlists
foreach (VzaarApi\PlaylistsList::each_item() as $playlist) {
  echo 'Playlist: ' . $playlist->id . PHP_EOL;
}

// Paginate Playlists
$params = ['per_page' => '2'];
$pager  = VzaarApi\PlaylistsList::paginate($params);

foreach ($pager as $playlist) {
  echo 'Playlist: ' . $playlist->id . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 1,
		  "title": "drj-playlist-cat-user-test",
		  "sort_order": "asc",
      "sort_by": "created_at",
      "max_vids": 30,
      "position": "left",
      "private": false,
      "dimensions": "auto",
      "autoplay": false,
      "continuous_play": false,
      "category_id": 42,
      "embed_code": "<iframe id=\"vzpl-1\" name=\"vzpl-1\" title=\"vzaar video player\" class=\"vzaar video player\" type=\"text/html\" width=\"927\" height=\"432\" frameborder=\"0\" allowFullScreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.localhost/playlists/1\"></iframe>",
      "videos": [
          {
              "id": 7574853,
              "title": "multipart",
              "user_id": 42,
              "description": "",
              "duration": 5.6,
              "created_at": "2016-11-11T11:36:26.000Z",
              "updated_at": "2016-11-11T11:36:26.000Z",
              "private": false
          },
          {
              "id": 7574854,
              "title": "multipart",
              "user_id": 42,
              "description": "",
              "duration": 5.6,
              "created_at": "2016-11-11T11:36:26.000Z",
              "updated_at": "2016-11-11T11:36:26.000Z",
              "private": false
          }
      ],
      "created_at": "2016-11-09T11:01:38.000Z",
      "updated_at": "2016-11-25T13:30:41.000Z"
    }
  ],
  "meta": {
    "total_count": 2,
    "links": {
      "first": "http://api.vzaar.com/api/v2/feeds/playlists?page=1&per_page=1",
      "next": "http://api.vzaar.com/api/v2/feeds/playlists?page=2&per_page=1",
      "previous": null,
      "last": "http://api.vzaar.com/api/v2/feeds/playlists?page=2&per_page=1"
    }
  }
}

Query Params

sort
string

Playlist attribute to sort results on— acceptable values are title / created_at

order
string

Specify sort order — acceptable values are: asc / desc

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result — maximum value is 50

 

Lookup Playlist

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/feeds/playlists/id
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/feeds/playlists/42"
playlist = VzaarApi::Playlist.find(42)
puts playlist.id
=> 42
<?php

$playlist = VzaarApi\Playlist::find(42);
echo 'Playlist: ' . $playlist->id;
A binary file was returned

You couldn't be authenticated

{
    "data": {
        "id": 42,
        "category_id": 446,
        "title": "Playlist Title",
        "sort_by": "created_at",
        "sort_order": "asc",
        "max_vids": 10,
        "position": "top",
        "private": false,
        "dimensions": "auto",
        "autoplay": false,
        "continuous_play": false,
        "embed_code": "<iframe id=\"vzpl-42\" name=\"vzpl-12949\" title=\"video player\" class=\"video player\" type=\"text/html\" width=\"768\" height=\"562\" frameborder=\"0\" allowFullScreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.localhost/playlists/42\"></iframe>",
      	"videos": [
            {
                "id": 7574853,
                "title": "multipart",
                "user_id": 42,
                "description": "",
                "duration": 5.6,
                "created_at": "2016-11-11T11:36:26.000Z",
                "updated_at": "2016-11-11T11:36:26.000Z",
                "private": false
            },
            {
                "id": 7574854,
                "title": "multipart",
                "user_id": 42,
                "description": "",
                "duration": 5.6,
                "created_at": "2016-11-11T11:36:26.000Z",
                "updated_at": "2016-11-11T11:36:26.000Z",
                "private": false
            }
        ],
        "created_at": "2017-10-12T18:22:03.000Z",
        "updated_at": "2017-10-25T06:31:08.000Z"
    }
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Playlist ID

 

Create Playlist

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/feeds/playlists
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "category_id": 12,
       "title": "My playlist"
     }' 
     "https://api.vzaar.com/api/v2/feeds/playlists"
VzaarApi::Playlist.create(category_id: 42, title: 'playlist test')
<?php

$playlist = [
  'title'       => 'playlist test',
  'category_id' => 42,
];

VzaarApi\Playlist::create($playlist);
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "category_id": 42,
    "title": "test",
    "sort_order": "desc",
    "sort_by": "created_at",
    "max_vids": 43,
    "position": "top",
    "private": false,
    "dimensions": "768x340",
    "autoplay": true,
    "continuous_play": true,
    "embed_code": "<iframe id=\"vzpl-1\" name=\"vzpl-1\" title=\"vzaar video player\" class=\"vzaar video player\" type=\"text/html\" width=\"768\" height=\"492\" frameborder=\"0\" allowFullScreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.localhost/playlists/1\"></iframe>",
    "created_at": "2017-03-20T11:30:36.932Z",
    "updated_at": "2017-03-20T11:30:36.932Z"
  }
}

Body Params

title
string
required

Playlist title

category_id
int32
required

Category ID of videos to include in Playlist

sort_by
string

Sort field for the playlist videos. Must be one of title, created_at, or custom

sort_order
string

Sort order for the playlist videos

private
boolean

if the playlist is private, it cannot be viewed by others on the vzaar website

dimensions
string

Width and height for the playlist, must be in the format 780x340

max_vids
int32

The maximum number of videos in the playlist

position
string

Which side the playlist controls show. Must be one of top, right, bottom, left

autoplay
boolean

Should the first video in the playlist autoplay

continuous_play
boolean

Should all the videos autoplay after each finishes

video_ids
array of integers

An array of video IDs in a custom order — this will order the videos in the playlist accordingly but only if sort_by is set to custom

 

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Update Playlist

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/feeds/playlists/id
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "title": "New playlist name"
     }' "https://api.vzaar.com/api/v2/feeds/playlists/1"
playlist = VzaarApi::Playlist.find(1)

playlist.title = "new name"
playlist.save
<?php

$playlist = VzaarApi\Playlist::find(42);
$playlist->name = "My Updated Playlist";
$playlist->save();
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "category_id": 42,
    "title": "test",
    "sort_order": "desc",
    "sort_by": "created_at",
    "max_vids": 43,
    "position": "bottom",
    "private": false,
    "dimensions": "768x340",
    "autoplay": true,
    "continuous_play": true,
    "embed_code": "<iframe id=\"vzpl-1\" name=\"vzpl-1\" title=\"vzaar video player\" class=\"vzaar video player\" type=\"text/html\" width=\"768\" height=\"482\" frameborder=\"0\" allowFullScreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.localhost/playlists/1\"></iframe>",
    "created_at": "2017-03-20T11:30:36.932Z",
    "updated_at": "2017-03-20T11:30:36.932Z"
  }
}

Path Params

id
int32
required

Playlist ID

Body Params

title
string

Playlist title

category_id
string

Category ID of videos to include in Playlist

sort_by
string

Sort field for the playlist videos. Must be one of title, created_at, or custom

sort_order
string

Sort order for the playlist videos

private
boolean

if the playlist is private, it cannot be viewed by others on the vzaar website

dimensions
string

Width and height for the playlist, must be in the format 780x340

max_vids
int32

The maximum number of videos in the playlist

position
string

Which side the playlist controls show. Must be one of top, right, bottom, left

autoplay
boolean

Should the first video in the playlist autoplay

continuous_play
boolean

Should all the videos autoplay after each finishes

video_ids
array of integers

An array of video IDs in a custom order — this will order the videos in the playlist accordingly but only if sort_by is set to custom

 

Delete Playlist

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vzaar.com/api/v2/feeds/playlists/id
curl -X DELETE \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/feeds/playlists/1"
playlist = VzaarApi::Playlist.find(1)

playlist.delete
<?php

$playlist = VzaarApi\Playlist::find(42);
$playlist->delete();
A binary file was returned

You couldn't be authenticated

{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Playlist ID

 

Set Image Frame

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/videos/id/image
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -d '{"time": 10.20}' \ 
     "https://api.vzaar.com/api/v2/videos/123/image"
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Video",
    "description": "Video Description goes here",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "categories": [],
    "adverts": [],
    "renditions": []
  }
}
{
  "errors": [
    {
      "message": "Poster creation failed",
      "detail": "Invalid data"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

Body Params

time
float

Seconds into video to generate poster frame from

 

Time in Seconds

Time supports up to 2 decimal places, so it's the same format returned by the JS API.

Upload Image Frame

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/videos/id/image
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \     
     -F "image=@my_image.jpg" \
        "https://api.vzaar.com/api/v2/videos/123/image"
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "title": "My Video",
    "description": "Video Description goes here",
    "state": "ready",
    "private": false,
    "user_id": 42,
    "user_login": "my-login",
    "account_id": 101,
    "account_name": "my-account",
    "duration": 1050,
    "created_at": "2018-01-17T15:48:44.000Z",
    "updated_at": "2018-01-17T18:02:06.000Z",
    "url": "https://vzaar.com/videos/123",
    "seo_url": null,
    "asset_url": "https://view.vzaar.com/123/video",
    "poster_url": "https://view.vzaar.com/123/image",
    "thumbnail_url": "https://view.vzaar.com/123/thumb",
    "embed_code": "<iframe id=\"vzvd-123\" name=\"vzvd-123\" title=\"video player\" class=\"video-player\" type=\"text/html\" width=\"448\" height=\"278\" frameborder=\"0\" allowfullscreen allowTransparency=\"true\" mozallowfullscreen webkitAllowFullScreen src=\"//view.vzaar.com/123/player\"></iframe>",
    "categories": [],
    "adverts": [],
    "renditions": []
  }
}
{
  "errors": [
    {
      "message": "Poster creation failed",
      "detail": "Invalid data"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

Body Params

image
file
required

Poster Frame image

optimize
boolean

Whether the image should be optimized for quick delivery, defaults to false — COMING SOON

 

List Subtitles

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/videos/id/subtitles
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/videos/123/subtitles"
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 123,
      "code": "en",
      "title": "english-subtitles.srt",
      "language": "English",
      "created_at": "2018-02-07T15:49:05Z",
      "updated_at": "2018-02-07T15:49:05Z",
      "url": "https://view.vzaar.com/subtitles/123"
    },
    {
      "id": 456,
      "code": "fr",
      "title": "french-subtitles.srt",
      "language": "French",
      "created_at": "2018-02-07T15:49:05Z",
      "updated_at": "2018-02-07T15:49:05Z",
      "url": "https://view.vzaar.com/subtitles/456"
    }
  ],
  "meta": {
    "total_count": 2,
    "links": {
      "first": "http://api.vzaar.com/api/v2/videos/123/subtitles?page=1",
      "next": "http://api.vzaar.com/api/v2/videos/123/subtitles?page=2",
      "previous": null,
      "last": "http://api.vzaar.com/api/v2/videos/123/subtitles?page=2"
    }
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Path Params

id
int32
required

Video ID

 

Language Support

vzaar supports ISO 639-1 two-letter codes as well as the following additional languages:

  • zh-Hans: Chinese Simplified
  • zh-Hant: Chinese Traditional
  • fr-ca: French (Canadian)
  • pt-br: Portuguese (Brazilian)

See https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

Create Subtitle

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/videos/id/subtitles
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "code": "en",
       "content": "1\n00:00:00,498 --> 00:00:02,827\nMy Subtitles"
     }' "https://api.vzaar.com/api/v2/videos/123/subtitles"
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "code": "en",
    "title": "english-subtitles.srt",
    "language": "English",
    "created_at": "2018-02-07T15:49:05Z",
    "updated_at": "2018-02-07T15:49:05Z",
    "url": "https://view.vzaar.com/subtitles/123"
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}
{
  "errors": [
    {
      "message": "Unprocessable Entity",
      "detail": "Subtitles already exist for language code 'en'"
    }
  ]
}

Path Params

id
int32
required

Video ID

Body Params

code
string
required

Language code

title
string

Name for subtitle file

content
string

Subtitle content

file
file

Subtitle file

 

File or Content

You must provide one (but not both) of file or content and if sending content then newlines must be represented with \n to be valid JSON.

File example

curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -F "code=en" \
     -F "file=@/path/to/file.srt" \
     "https://api.vzaar.com/api/v2/videos/123/subtitles"

Update Subtitle

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/videos/id/subtitles/subtitle
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "code": "en",
       "content": "1\n00:00:00,498 --> 00:00:02,827\nMy Subtitles"
     }' "https://api.vzaar.com/api/v2/videos/123/subtitles/321"
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 123,
    "code": "en",
    "title": "english-subtitles.srt",
    "language": "English",
    "created_at": "2018-02-07T15:49:05Z",
    "updated_at": "2018-02-07T15:49:05Z",
    "url": "https://view.vzaar.com/subtitles/123"
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Path Params

id
int32
required

Video ID

subtitle
int32
required

Subtitle ID

Body Params

code
string
required

Language code

title
string

Name for subtitle file

content
string

Subtitle content

file
file

Subtitle file

 

File or Content

You must provide one (but not both) of file or content. To upload a file, send form data and to provide content, send JSON.

Delete Subtitle

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vzaar.com/api/v2/videos/id/subtitles/subtitle
curl -X DELETE \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/videos/123/subtitles/321"
A binary file was returned

You couldn't be authenticated

{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Video ID

subtitle
int32
required

Subtitle ID

 

List Ingest Recipes

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/ingest_recipes
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/ingest_recipes"
# iterate over all ingest recipes
VzaarApi::IngestRecipe.each_item do |recipe|
  puts recipe.name
end

# paginate ingest recipes
pager = VzaarApi::IngestRecipe.paginate
pager.first.each do |recipe|
  puts recipe.name
end
<?php

// Iterate over all Recipes
foreach (VzaarApi\RecipesList::each_item() as $recipe) {
  echo 'Recipe: ' . $recipe->id . PHP_EOL;
}

// Paginate Recipes
$params = ['per_page' => '2'];
$pager  = VzaarApi\RecipesList::paginate($params);

foreach ($pager as $recipe) {
  echo 'Recipe: ' . $recipe->id . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 1,
      "name": "My recipe",
      "recipe_type": "new_video",
      "description": "Test",
      "account_id": 79357,
      "user_id": 79357,
      "default": true,
      "multipass": false,
      "frame_grab_time": "3.5",
      "generate_animated_thumb": true,
      "generate_sprite": true,
      "use_watermark": true,
      "send_to_youtube": false,
      "notify_by_email": false,
      "notify_by_pingback": false,
      "encoding_presets": [
        {
          "id": 2,
          "name": "Do Not Encode",
          "description": "",
          "output_format": "mp4",
          "bitrate_kbps": null,
          "max_bitrate_kbps": null,
          "long_dimension": null,
          "video_codec": null,
          "profile": "MP3",
          "frame_rate_upper_threshold": null,
          "audio_bitrate_kbps": null,
          "audio_channels": null,
          "audio_sample_rate": null,
          "created_at": "2016-11-09T11:01:38.000Z",
          "updated_at": "2016-11-09T11:01:38.000Z"
        }
      ],
      "created_at": "2016-11-09T11:01:38.000Z",
      "updated_at": "2016-11-25T13:30:41.000Z"
    }
  ],
  "meta": {
    "total_count": 2,
    "links": {
      "first": "http://api.vzaar.com/api/v2/ingest_recipes?page=1&per_page=1",
      "next": "http://api.vzaar.com/api/v2/ingest_recipes?page=2&per_page=1",
      "previous": null,
      "last": "http://api.vzaar.com/api/v2/ingest_recipes?page=2&per_page=1"
    }
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Query Params

sort
string

Recipe attributes to sort results with — acceptable values are: id / name

order
string

Specify sort order — acceptable values are: asc / desc

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result — maximum value is 50

 

Lookup Ingest Recipe

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/ingest_recipes/id
curl -X GET \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     "https://api.vzaar.com/api/v2/ingest_recipes/1"
recipe = VzaarApi::IngestRecipe.find(42)
puts recipe.id
=> 42
<?php

$recipe = VzaarApi\Recipe::find(42);
echo 'Recipe: ' . $recipe->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "name": "Ingest recipe 1",
    "recipe_type": "new_video",
    "description": null,
    "account_id": 1,
    "user_id": 42,
    "default": true,
    "multipass": false,
    "frame_grab_time": "3.5",
    "generate_animated_thumb": true,
    "generate_sprite": true,
    "use_watermark": false,
    "send_to_youtube": true,
    "notify_by_email": false,
    "notify_by_pingback": false,
    "encoding_presets": [
      {
        "id": 4,
        "name": "LD",
        "description": "Low Definition",
        "output_format": "mp4",
        "bitrate_kbps": 400,
        "max_bitrate_kbps": 520,
        "long_dimension": 480,
        "video_codec": "libx264",
        "profile": "main",
        "frame_rate_upper_threshold": "29.97",
        "audio_bitrate_kbps": 128,
        "audio_channels": 2,
        "audio_sample_rate": 44100,
        "created_at": "2016-10-24T12:36:47.000Z",
        "updated_at": "2016-10-24T12:36:47.000Z"
      },
      {
        "id": 5,
        "name": "SD - Lower",
        "description": "Our lower Standard Definition rendition",
        "output_format": "mp4",
        "bitrate_kbps": 800,
        "max_bitrate_kbps": 1040,
        "long_dimension": 640,
        "video_codec": "libx264",
        "profile": "main",
        "frame_rate_upper_threshold": "29.97",
        "audio_bitrate_kbps": 128,
        "audio_channels": 2,
        "audio_sample_rate": 44100,
        "created_at": "2016-10-24T12:36:47.000Z",
        "updated_at": "2016-10-24T12:36:47.000Z"
      }
    ],
    "created_at": "2016-10-26T11:00:55.000Z",
    "updated_at": "2016-10-26T11:00:55.000Z"
  }
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Recipe ID

 

Create Ingest Recipe

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vzaar.com/api/v2/ingest_recipes
curl -X POST \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Ingest recipe 1",
       "default": true,
       "multipass": false,
       "frame_grab_time": "3.5",
       "generate_animated_thumb": true,
       "generate_sprite": true,
       "use_watermark": false,
       "send_to_youtube": true,
       "notify_by_email": false,
       "notify_by_pingback": false,
       "encoding_preset_ids": [4, 5]
     }' "https://api.vzaar.com/api/v2/ingest_recipes"
ids = VzaarApi::EncodingPreset.each_item.map(&:id)
attrs = {
  name: 'my recipe',
  encoding_preset_ids: ids
}
recipe = VzaarApi::IngestRecipe.create attrs
<?php

// Recipe params
$params = [
  'default'             => true,
  'encoding_preset_ids' => [1, 2, 3],
];

// Create new Default Recipe
$recipe = VzaarApi\Recipe::create($params);
echo 'Recipe: ' . $recipe->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "name": "Ingest recipe 1",
    "recipe_type": "new_video",
    "description": null,
    "account_id": 1,
    "user_id": 42,
    "default": true,
    "multipass": false,
    "frame_grab_time": "3.5",
    "generate_animated_thumb": true,
    "generate_sprite": true,
    "use_watermark": false,
    "send_to_youtube": true,
    "notify_by_email": false,
    "notify_by_pingback": false,
    "encoding_presets": [
      {
        "id": 4,
        "name": "LD",
        "description": "Low Definition",
        "output_format": "mp4",
        "bitrate_kbps": 400,
        "max_bitrate_kbps": 520,
        "long_dimension": 480,
        "video_codec": "libx264",
        "profile": "main",
        "frame_rate_upper_threshold": "29.97",
        "audio_bitrate_kbps": 128,
        "audio_channels": 2,
        "audio_sample_rate": 44100,
        "created_at": "2016-10-24T12:36:47.000Z",
        "updated_at": "2016-10-24T12:36:47.000Z"
      },
      {
        "id": 5,
        "name": "SD - Lower",
        "description": "Our lower Standard Definition rendition",
        "output_format": "mp4",
        "bitrate_kbps": 800,
        "max_bitrate_kbps": 1040,
        "long_dimension": 640,
        "video_codec": "libx264",
        "profile": "main",
        "frame_rate_upper_threshold": "29.97",
        "audio_bitrate_kbps": 128,
        "audio_channels": 2,
        "audio_sample_rate": 44100,
        "created_at": "2016-10-24T12:36:47.000Z",
        "updated_at": "2016-10-24T12:36:47.000Z"
      }
    ],
    "created_at": "2016-10-26T11:00:55.000Z",
    "updated_at": "2016-10-26T11:00:55.000Z"
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "Validation failed: At least one encoding preset is required"
    }
  ]
}

Body Params

name
string
required

Recipe name

description
string

Recipe description

encoding_preset_ids
array of integers
required

List of encoding preset id values to associate with this recipe

default
boolean

Flag this recipe as my default recipe — if another recipe is currently the default it will be set to default=false

multipass
boolean

Perform multipass encoding (this will slow down your video processing but yield better quality results)

generate_animated_thumb
boolean

Generate an animated gif thumbnail

generate_sprite
boolean

Generate sprites (used for scrubbing thumbnails in the vzaar player)

use_watermark
boolean

Burn your watermark into the transcoded video (requires additional watermark setup)

send_to_youtube
boolean

Send your video to your associated YouTube account (requires YouTube syndication access and additional setup)

notify_by_email
boolean

Send email notification after video processing

notify_by_pingback
boolean

Send http pingback after video processing

 

Default ingest recipe

If you do not specify the ingest recipe to be used when creating a video, vzaar will use your default ingest recipe for processing. If you specify an ingest recipe to be used at the time of video creation, vzaar will use the specified ingest recipe.

You can only have one default ingest recipe, so updating an ingest recipe and setting the new default value to true will result in the previous default ingest recipe also being updated (setting default to false).

Encoding presets

An ingest recipe cannot be saved without at least one encoding preset. You can see which presets are available to you (based on your account) by retrieving the list of encoding presets. You will only be able to use presets in this list when saving an ingest recipe.

Update Ingest Recipe

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://vzaar.com/api/v2/recipes/id
curl -X PATCH \
     -H "X-Client-Id: <client_id>" \
     -H "X-Auth-Token: <auth_token>" \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Recipe 1",
       "default": true,
       "multipass": false,
       "generate_animated_thumb": false,
       "generate_sprite": false,
       "use_watermark": false,
       "send_to_youtube": false,
       "notify_by_email": false,
       "notify_by_pingback": false,
       "encoding_preset_ids": [4]
     }' "https://api.vzaar.com/api/v2/ingest_recipes/1"
recipe = VzaarApi::IngestRecipe.find(42)
recipe.default = true
recipe.description = 'updated!'
recipe.save

# updating encoding presets
ids = VzaarApi::EncodingPreset.each_item.map(&:id)
recipe.encoding_preset_ids = ids
recipe.save
<?php

$recipe = VzaarApi\Recipe::find(42);
$recipe->name = 'My Updated Recipe';
$recipe->encoding_preset_ids = [4, 5, 6];

if ($recipe->edited()) {
  $recipe->save();
}
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 1,
    "name": "Recipe 1",
    "recipe_type": "new_video",
    "description": null,
    "account_id": 1,
    "user_id": 42,
    "default": true,
    "multipass": false,
    "frame_grab_time": "3.5",
    "generate_animated_thumb": false,
    "generate_sprite": false,
    "use_watermark": false,
    "send_to_youtube": true,
    "notify_by_email": false,
    "notify_by_pingback": false,
    "encoding_presets": [
      {
        "id": 4,
        "name": "LD",
        "description": "Low Definition",
        "output_format": "mp4",
        "bitrate_kbps": 400,
        "max_bitrate_kbps": 520,
        "long_dimension": 480,
        "video_codec": "libx264",
        "profile": "main",
        "frame_rate_upper_threshold": "29.97",
        "audio_bitrate_kbps": 128,
        "audio_channels": 2,
        "audio_sample_rate": 44100,
        "created_at": "2016-10-24T12:36:47.000Z",
        "updated_at": "2016-10-24T12:36:47.000Z"
      }
    ],
    "created_at": "2016-10-26T11:00:55.000Z",
    "updated_at": "2016-11-26T11:00:55.000Z"
  }
}
{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "You cannot unflag your default ingest recipe"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Recipe ID

Body Params

name
string

Recipe name

description
string

Recipe description

encoding_preset_ids
array of integers

List of encoding preset id values to associate with this recipe

default
boolean

Flag this recipe as my default recipe — if another recipe is currently the default it will be set to default=false

multipass
boolean

Perform multipass encoding (this will slow down your video processing but yield better quality results)

generate_animated_thumb
boolean

Generate an animated gif thumbnail

generate_sprite
boolean

Generate sprites (used for scrubbing thumbnails in the vzaar player)

use_watermark
boolean

Burn your watermark into the transcoded video (requires additional watermark setup)

send_to_youtube
boolean

Send your video to your associated YouTube account (requires YouTube syndication access and additional setup)

notify_by_email
boolean

Send email notification after video processing

notify_by_pingback
boolean

Send http pingback after video processing

 

Delete Ingest Recipe

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vzaar.com/api/v2/ingest_recipes/id
curl -X DELETE \
     -H "X-Client-Id: <client-id>" \
     -H "X-Auth-Token: <auth-token>" \
     "https://api.vzaar.com/api/v2/ingest_recipes/1"
recipe = VzaarApi::IngestRecipe.find(42)
recipe.delete
<?php

$recipe = VzaarApi\Recipe::find(42);
$recipe->delete();
A binary file was returned

You couldn't be authenticated

{
  "errors": [
    {
      "message": "Invalid parameters",
      "detail": "You cannot delete your default ingest recipe"
    }
  ]
}
{
  "errors": [
    {
      "message": "Not found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Recipe ID

 

Default ingest recipe

If you try to delete your default ingest recipe you will receive an error response. In this case you will first need to update another ingest recipe as your new default, and then proceed to delete the original ingest recipe.

List Encoding Presets

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/encoding_presets
curl -X GET
     -H "X-Client-Id: <client-id>" \
     -H "X-Auth-Token: <auth-token>" \
     "https://api.vzaar.com/api/v2/encoding_presets"
# iterate over all encoding presets
VzaarApi::EncodingPreset.each_item do |preset|
  puts preset.name
end

# paginate encoding presets
pager = VzaarApi::EncodingPreset.paginate
pager.first.each do |preset|
  puts preset.name
end
<?php

// Iterate over all Presets
foreach (VzaarApi\PresetsList::each_item() as $preset) {
  echo 'Preset: ' . $preset->id . PHP_EOL;
}

// Paginate Presets
$params = ['per_page' => '2'];
$pager  = VzaarApi\PresetsList::paginate($params);

foreach ($pager as $preset) {
  echo 'Preset: ' . $preset->id . PHP_EOL;
}
A binary file was returned

You couldn't be authenticated

{
  "data": [
    {
      "id": 4,
      "name": "LD",
      "description": "Low Definition",
      "output_format": "mp4",
      "bitrate_kbps": 400,
      "max_bitrate_kbps": 520,
      "long_dimension": 480,
      "video_codec": "libx264",
      "profile": "main",
      "frame_rate_upper_threshold": "29.97",
      "audio_bitrate_kbps": 128,
      "audio_channels": 2,
      "audio_sample_rate": 44100,
      "created_at": "2016-10-24T12:36:47.000Z",
      "updated_at": "2016-10-24T12:36:47.000Z"
    },
    {
      "id": 5,
      "name": "SD - Lower",
      "description": "Our lower Standard Definition rendition",
      "output_format": "mp4",
      "bitrate_kbps": 800,
      "max_bitrate_kbps": 1040,
      "long_dimension": 640,
      "video_codec": "libx264",
      "profile": "main",
      "frame_rate_upper_threshold": "29.97",
      "audio_bitrate_kbps": 128,
      "audio_channels": 2,
      "audio_sample_rate": 44100,
      "created_at": "2016-10-24T12:36:47.000Z",
      "updated_at": "2016-10-24T12:36:47.000Z"
    }
  ],
  "meta": {
    "total_count": 9,
    "links": {
      "first": "http://api.vzaar.com/api/v2/encoding_presets?page=1",
      "next": "http://api.vzaar.com/api/v2/encoding_presets?page=3",
      "previous": "http://api.vzaar.com/api/v2/encoding_presets?page=1",
      "last": "http://api.vzaar.com/api/v2/encoding_presets?page=5"
    }
  }
}
{
  "errors": [
    {
      "message": "Authentication failed",
      "detail": "Invalid credentials"
    }
  ]
}

Query Params

sort
string

Stream attribute to sort results with — acceptable values are: id, name, bitrate_kbps

order
string

Specify sort order — acceptable values are: asc / desc

page
int32

Page number for paginated results

per_page
int32

Number of results per paginated page result — maximum value is 50

 

Lookup Encoding Preset

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vzaar.com/api/v2/encoding_presets/id
curl -X GET
     -H "X-Client-Id: <client-id>" \
     -H "X-Auth-Token: <auth-token>" \
     "https://api.vzaar.com/api/v2/encoding_presets/1"
preset = VzaarApi::EncodingPreset.find(42)
puts preset.id
=> 42
<?php

$preset = VzaarApi\Preset::find(42);
echo 'Preset: ' . $preset->id;
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "id": 3,
    "name": "ULD",
    "description": "Ultra Low Definition",
    "output_format": "mp4",
    "bitrate_kbps": 200,
    "max_bitrate_kbps": 260,
    "long_dimension": 416,
    "video_codec": "libx264",
    "profile": "main",
    "frame_rate_upper_threshold": "12.0",
    "audio_bitrate_kbps": 128,
    "audio_channels": 2,
    "audio_sample_rate": 44100,
    "created_at": "2016-10-24T12:36:47.000Z",
    "updated_at": "2016-10-24T12:36:47.000Z"
  }
}
{
  "errors": [
    {
      "message": "Not Found",
      "detail": "Requested resource cannot be found"
    }
  ]
}

Path Params

id
int32
required

Encoding Preset ID