API Overview

Getting Started

Below you'll find tutorials for using the VHX 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 VHX Dashboard here Get API Key

5 Steps

Step 1 - Create a Video

Upload and ingest video into the VHX Dashboard. VHX 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 api@vhx.tv 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 VHX 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 VHX 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 VHX 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 VHX Player API for custom interactions with the VHX Player.-->
<script src="https://cdn.vhx.tv/assets/player.js"></script>

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

Developer Support

We're always happy to help out with code or answer any questions you might have. Get in touch on our Slack Channel or email us at api@vhx.tv.

VHX Support on Slack

Client Libraries

To make integrating with the VHX 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!


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.


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.


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.


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


VHX Demo Site

To get an idea of how you might use the VHX API for your own project, check out the VHX 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