API Overview

Getting Started

Below you'll find tutorials for using the Vimeo OTT API to integrate your experiences with our video services. For more in depth information on all our available endpoints see the full API Reference.

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.

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.

  $ curl -X POST "https://api.vhx.tv/customers" \
  -d name="First Last" \
  -d email="customer@email.com" \
  -d product="https://api.vhx.tv/products/1" \
  -d plan="standard" \
  -u o3g_4jLUrxHpc9rsoh3DHfpsq1L6oyM:

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:

$ curl -X POST "https://api.vhx.tv/authorizations" \
  -d customer="https://api.vhx.tv/customers/1" \
  -d video="https://api.vhx.tv/videos/1" \
  -u o3g4jLU-rxHpc9rsoh3DHfpsq1L6oyM:

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/videos/1?authorization=QVJ-cavyvwSX6JpafMCX7zsd1wKg2XfDuZnN\" width="850" height="480" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

<!-- 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! Please submit any questions here.