Working With Images

By just adjusting a few query string parameters on an image's URL, you can resize, crop, and rotate it.

This is especially useful when you're working with the Data API or oEmbed endpoint and want a video's thumbnail image at a different size.

📝

Note

These instructions will all be for working with an image URL that comes from an asset of your video.

📝

Note

The Wistia APIs were specifically built for videos in projects. We do not formally support using our APIs for audio files in projects, or audio or video episodes in Channels at this time. For the most reliable experience, we recommend continuing to use these for videos in projects.

The Parameters

Cropping, resizing, rotating, or adding a Wistia play button onto an image is easy peasy. Here are the parameters you need to know about!

"Geometry Strings" follow the same format Image Magick uses for resizing and cropping images. Here is a good reference on geometry strings.

Examples

Let's start with this image of Lenny's face:

https://embed-ssl.wistia.com/deliveries/8669acc30fdfe63a25ad9d32f5a9f664.jpg

What if we want a mini Lenny that's exactly 100x50 pixels? We use the image_crop_resized parameter like this:

https://embed-ssl.wistia.com/deliveries/8669acc30fdfe63a25ad9d32f5a9f664.jpg?image_crop_resized=100x50

Now let's say we want a sideways Lenny that's 200 pixels wide. We can use image_rotate and image_resize:

https://embed-ssl.wistia.com/deliveries/8669acc30fdfe63a25ad9d32f5a9f664.jpg?image_rotate=90&image_resize=200

And finally, let's put a pink play button on him with image_play_button and image_play_button_color:

https://embed-ssl.wistia.com/deliveries/8669acc30fdfe63a25ad9d32f5a9f664.jpg?image_play_button=true&image_play_button_color=FF5CCDA0

Using oEmbed

When using the oEmbed endpoint, part of the JSON returned is the thumbnail_url. By parsing that and appending parameters (listed above), we can generate a thumbnail image (for a custom popover implementation, or for showing decoratively on the page).

First, we'll make the oEmbed request:

https://fast.wistia.net/oembed?url=https://home.wistia.com/medias/e4a27b971d?embedType=async&videoWidth=640

The JSON returned:

{
  "version":"1.0",
  "type":"video",
  "html":"<script charset=\"ISO-8859-1\" src=\"//fast.wistia.com/assets/external/E-v1.js\" async></script><div class=\"wistia_embed wistia_async_e4a27b971d\" style=\"height:360px;width:640px\">&nbsp;</div>",
  "width":640,
  "height":360,
  "provider_name":"Wistia, Inc.",
  "provider_url":"https://wistia.com",
  "title":"Brendan - Make It Clap",
  "thumbnail_url":"https://embed-ssl.wistia.com/deliveries/2d2c14e15face1e0cc7aac98ebd5b6f040b950b5.jpg?image_crop_resized=640x360",
  "thumbnail_width":640,
  "thumbnail_height":360,
  "duration":16.43
}

Parse out that thumbnail_url!

thumbnail_url = json_object.thumbnail_url
=> "https://embed-ssl.wistia.com/deliveries/2d2c14e15face1e0cc7aac98ebd5b6f040b950b5.jpg?image_crop_resized=640x360"

That thumbnail includes ?image_crop_resized=640x360 by default. You desperately want to resize it to be 450 pixels wide. No problem! We'll use the image_resize parameter:

thumbnail_url = json_object.thumbnail_url + '&' + 'image_resize=450'

We could have also "chopped off" the existing image_crop_resized parameter first, and then appended the image_resize using a ? instead of an ampersand.

Using the Wistia Data API Ruby Gem

When making a request against the Data API, the media assets includes an array of assets.

m = Wistia::Media.first
m.assets.select{ |a| a.attributes["type"] == "OriginalFile" }.first
=> #<Wistia::Media::Asset:0x007fa67caced68 @attributes={
    "url"=>"https://embed-ssl.wistia.com/deliveries/b300126144f62ba2942ec4a4f29e949a47e16f12.bin",
    "width"=>640, "height"=>360, "fileSize"=>48442, "contentType"=>"video/mp4",
    "type"=>"OriginalFile"
  }, @prefix_options={}, @persisted=false>
url = _.url
=> "https://embed-ssl.wistia.com/deliveries/b300126144f62ba2942ec4a4f29e949a47e16f12.bin"

You can then apply the same geometry strings to this URL. You'll also have to change that .bin extension to .jpg.

name  = url.chomp(File.extname(url)) + ".jpg?image_crop_resized=640x360"
=> "https://embed-ssl.wistia.com/deliveries/b300126144f62ba2942ec4a4f29e949a47e16f12.jpg?image_crop_resized=640x360"

Uploading a Thumbnail via API

To upload a thumbnail via the Wistia API, you’ll need to use a combination of our Upload API and the Medias endpoint of our Data API.

1. Upload the thumbnail file to Wistia using the URL where it’s hosted. You will need to use the Upload API to make the request.
2. The response to this POST request will include a hashed_id parameter that references the image file you've just uploaded to Wistia. You can see an example of the response format here.
3. Use the Medias: Update method and pass that hashed_id as the new_still_media_id parameter.

Pretty fun, right?