API Overview

Getting Started

Below you'll find tutorials for using the Vimeo OTT API to integrate your experiences with our video services. Use the code toggle above to see code examples in your language of choice.

For more in depth information on all our available endpoints see the full API Reference. For more information on using our client libraries see the languages listed to the left.

If you haven't already you can get your API Key from the Vimeo OTT Dashboard here Get API Key

5 Steps

Step 1 - Create a Video

Upload and ingest video into the Vimeo OTT Dashboard. Vimeo OTT will automatically transcode into various renditions to ensure fast, reliable adaptive streaming across all devices. If you have a larger library of content, please contact apiott@vimeo.com for ingest assistance.

Step 2 - Create a Product

Once you have your videos uploaded you'll need a way for customers to access your content. Content can be accessed by creating a product. Products allow you to specify what the access agreement is and what videos/collections are associated with that product. An access agreement can one of the following:

  • Recurring Product

    (a subscription)

  • Expiring Product

    (a rental)

  • Permanent Product

    (a purchase)

Products can be created via the Vimeo OTT Dashboard. You'll need a reference to the product you create in subsequent API calls: the product href can be retrieved for any product after creation in the dashboard. It follows a similar pattern to videos, https://api.vhx.tv/products/:id.

Step 3 - Create a Customer

Once you have your videos and products ready to go you'll be ready to accept customers. To give access to your products you will need to create a customer. To create a customer with the API you must the customer name, email, and product you're granting them access to.

vhx = Vhx.setup({ api_key: 'oxEU89zLkRTED2P_sKbYRCJSbT4BVjZm' })

# create a vhx customer
customer = Vhx::Customer.create({
   name: 'Customer Name',
   email: 'customer@vhx.tv',
   product: 'https://api.vhx.tv/products/1'
});

Note: When using our API, it is assumed your application will handle any necessary pay wall (we recommend Stripe) and user authentication. It is possible, though, to leverage the API to build your own custom web experience (using Stripe), and still use our branded apps platform which natively supports and handles Roku Billing, Apple IAP, and Android IAP on your behalf.

Step 4 - Authorize a Customer

The final step is to grant a customer access to a specific video via authorizations and the Vimeo OTT HTML5 player. You can specify how long a particular session token lasts. Once a token expires, you will need to re-authenticate your customer and create a new authorization token. To create an authorization token for a customer with the API:

vhx = Vhx.setup({ api_key: 'oxEU89zLkRTED2P_sKbYRCJSbT4BVjZm' })

# authorize access to video
authorization = Vhx::Authorization.create({
  expires_in: 3000,
  customer: 'https://api.vhx.tv/customers/1',
  video: 'https://api.vhx.tv/videos/1'
});

Step 5 - Output the Authorized Player

From our previous authorization call we'll get back an object with all that we need to include an authorized instance of your video. You can either include the Vimeo OTT Player yourself with the video and authorization token or simply output the player embed from the object embed property:

<iframe src="https://embed.vhx.tv/<%= authorization[:player][:path] %>?autoplay=1&authorization=<%= authorization[:token] %>" width="850" height="480" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>
<!-- or -->
<%= authorization[:player][:html] %>

<!-- include the Vimeo OTT Player API for custom interactions with the Vimeo OTT Player.-->
<script src="https://cdn.vhx.tv/assets/player.js"></script>

See our Vimeo OTT Player Guide for more details on using the Vimeo OTT Player and API.

Developer Support

We're always happy to help out with code or answer any questions you might have. Get in touch by dropping us an email.

apiott@vimeo.com

Client Libraries

To make integrating with the Vimeo OTT API as easy as possible we offer several client libraries. Installation instructions below. If your language of choice is not included, please let us know!

Ruby

The Ruby library is available as a gem.

$ gem install vhx-ruby

If you use bundler, you can use this line:

gem 'vhx-ruby', :git => 'https://github.com/vhx/vhx-ruby'

Visit our Ruby API docs for more details, or see the source on GitHub.

Node.js

The Node library can be installed via npm.

$ npm install vhx

Visit our Node.js API docs for more details, or see the source on GitHub.

PHP

The PHP library can be installed via Composer. Simply add the following to your composer.json file:

{
  "require": {
    "vhx/vhx-php": "1.3.*"
  }
}

Alternatively, you can download the source directly and use the PHP library manually.

require_once('/path/to/vhx-php/init.php');

Visit our PHP API docs for more details, or see the source on GitHub.

Examples

Vimeo OTT Demo Site

To get an idea of how you might use the Vimeo OTT API for your own project, check out the Vimeo OTT Demo Site. Demo Site

You can view the code (written in Nodejs) for the site on GitHub.

Note: More language examples of the demo site coming soon