Warning: You are heading into developer territory!
Our APIs are designed for programmers. If our APIs were a ski trail, they would be a nice blue square cruiser - good if you know how to ski, but not for beginners.
Only move forward if you are comfortable working with APIs, or have a friend nearby that is.
You may find yourself needing to build embed codes for your videos dynamically.
The Data API approach is good for lots of videos and dynamically updated content.
The oEmbed approach is best when you have the URL for your video - just plug it in with the parameters you want and get an embed code!
Once you have your embed code built, check out the Embedding Options and Plugins guide to add custom behavior to your embeds programmatically.
Our oEmbed endpoint is:
Currently, our oEmbed endpoint recognizes two URL formats.
iframe embed code URLs
You can build these for single videos or playlists, or generate them through your account.
example: http://fast.wistia.net/embed/iframe/ b0767e8ebb?version=v1&controlsVisibleOnLoad=true&playerColor=aae3d8
playlist example: http://fast.wistia.net/embed/playlists/fbe3880a4e?theme=trim &version=v1&videoOptions%5BvideoHeight%5D=360&videoOptions%5BvideoWidth%5D=640
Public Media URLs
Public Media URLs are the address to a video in your account.
It's likely we'll add more URLs to this list in the future.
If you're looking to automatically detect Wistia URLs and run them against our endpoint, we recommend using this regular expression:
Or if you don't speak regex, here's what we're matching:
1 2 3 4
Note, it's likely we'll add support for more URLs in the future so feel free to use a more general regular expression so you don't miss out on future enhancements! Perhaps this:
Get the embed code and some information for a video at ''http://home.wistia.com/medias/e4a27b971d'' in JSON format:
1 2 3 4 5 6 7 8 9 10 11 12 13
If you're looking for XML instead of JSON, use:
For all the fine details about the options supported, see the official oEmbed spec.
Our endpoint supports all the options detailed at oembed.com.
The required url parameter that's passed in supports all the options detailed in the Player API.
We also accept some additional parameters that can change the output of the embed code:
|embedType||string||Only applicable to videos and playlists. Accepts "iframe", "api", "seo", "popover", "playlist_iframe", and "playlist_api".|
|width||integer||The requested width of the video embed. Defaults to the native size of the video or 360, whichever is smaller.|
|height||integer||The requested height of the video embed. Defaults to the native size of the video or 640, whichever is smaller.|
|popoverHeight||integer||Only applicable to "popover" embed type. The requested height of the popover. Defaults to maintain the correct aspect ratio, with respect to the width.|
|popoverWidth||integer||Only applicable to "popover" embed type. The requested width of the popover. Defaults to 150.|
|ssl||boolean||Determines whether the embed code should use https. Defaults to false.|
If given a
(or any combination of those), the other dimensions in the resulting embed
code may change so that the video's aspect ratio is preserved.
These parameters are attached to the Wistia media URL, and not the oEmbed call. So they must be URL-encoded to travel with the Wistia URL.
In this example, we'll request an
First, the media URL we'll request:
Next, we'll add the parameters for our request:
We'll URL-encode this request:
We URL-encoded this request, because we want the parameters `embedType` and `handle` passed along to Wistia, not to the oEmbed endpoint.
And now use the oEmbed endpoint:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
Given the oEmbed
base URL, your
account URL, and a
media hashed id, we can
use the jQuery
getJSON function to call against the oEmbed endpoint to return
the video data.
Note this function also takes a callback function as a parameter. We'll set up that callback function next.
1 2 3 4 5 6 7
This function will return a JSON data object, and pass it to our callback function, which will parse the JSON and log the thumbnail URL. Let's write that callback function now:
1 2 3
Finally, we'll setup something to call these functions for our
media hashed id:
Working With The Thumbnail
Part of the JSON returned by the oEmbed is the
thumbnail_url. This URL is a
direct link to the thumbnail image asset. If your implementation involves using
the thumbnail image (i.e. building your own 'popover' embeds, displaying your
own play button, etc.) you should use this thumbnail image, which by default
has no Wistia play button overlaid on it.
See our working with Wistia images guide for more info!
- If an invalid URL (one that doesn't match our regular expression above) is given, the endpoint will return 404 Not Found.
- If an unparseable URL is given in the url param, the endpoint will return 404 Not Found.
- If a media is found but has no available embed code, the endpoint will return 501 Not Implemented. Video, Image, Audio, and Document files all currently implement oembeds.
- If a playlist is found but has no videos, the endpoint will return 501 Not Implemented.
Make Your Life Easier
If you're contemplating doing an oEmbed implementation with Wistia (or any oEmbed provider for that matter), we strongly recommend checking out Embedly. By integrating with them you'll have immediate access to over 100 oEmbed providers. They also have great documentation and ready-made libraries for every popular language, plus they're just nice guys!
Data API Approach
This is totally FYI: We've been recommending the oEmbed approach as the preferred method. It provides a simple way to generate Wistia embed codes without you having to write much code. The only downside is you'll have to make an extra request to get an embed code.
The hashed_id is a unique identifier to a video within the Wistia system. You can get hashed IDs for your videos programmatically using the Data API.
By-and-large, our embed codes are turnkey - the most important part is the hashed ID.
Building an iframe embed code
For this example we'll be using a hashed ID of
your hashed ID anywhere you see
First, build the base URL:
Next, you could customize the video parameters see more about customization:
You can also add plugin parameters. Plugins have parameters in their own namespace, using bracket notation:
It is good practice to URL encode both keys and values:
Finally we drop this src into an iframe, where we also specify the width and height.
Width and height should be the size of the entire embed (the video plus the plugins).
If you are using the Player API it's important to embed a video directly on the page (rather than using an iframe).
In this case we do the following:
First, add a div container to the page with a unique ID attribute. In our standard embeds, we use the video's hashed ID as the unique ID.
1 2 3
Next, include the Wistia library:
Now initialize the embed and pass in the video parameters:
1 2 3 4 5 6 7
Let's also include the socialbar in the embed code:
1 2 3 4 5 6 7 8 9 10 11 12
1 2 3 4 5 6 7 8 9 10 11
Building an SEO embed code
Unfortunately you can't programmatically build an SEO-compatible embed yourself right now.
Google's video search is a bit antiquated in that it can't properly detect
videos inside iframes (which is our preferred method of embedding video).
They only recognize the
<object><embed> style embed codes.
The good news is you can easily use the oEmbed approach to generate an SEO embed for you.
Embedding Options and Plugins
Once you have your embed code built, you probably want to tailor the appearance and behavior to your wishes. You may also want to add a plugin like Turnstile or a Call-to-Action.
For a list of available embedding options to be used with the Customize API, check our Embedding Options Documentation.