Working With Images

All the ways you can manipulate images returned by Wistia APIs.

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.

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!

image_resizeGeometry string used to resize the image
image_cropGeometry string used to crop the image (after it’s been resized)
image_crop_resizedGeometry string used to create an image of the exact specified size without distortion
image_play_buttonWhether or not to overlay a play button in the middle of the image. Specify either true or false.false
image_play_button_colorThe color of the play button. Specify an RGB or RGBA hex color string.68656080
image_rotateRotate the image clockwise by the specified number of degrees. For example, a value of 180 would flip the image upside-down.

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

When you're adjusting these parameters, our servers have to create these new images. In some cases, we can't make the new image immediately. When this happens, we will return a 202 Accepted response instead of the new image. Meanwhile, our server farm will be crunching away, creating that image for you so the next time you hit that URL it will be ready! So if you are playing around with these parameters in your browser and don't see the new image right away, don't worry. Just keep refreshing and it will be there soon (usually within 30 seconds).


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

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

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

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

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:

The JSON returned:

  "html":"<script charset=\"ISO-8859-1\" src=\"//\" async></script><div class=\"wistia_embed wistia_async_e4a27b971d\" style=\"height:360px;width:640px\">&nbsp;</div>",
  "provider_name":"Wistia, Inc.",
  "title":"Brendan - Make It Clap",

Parse out that thumbnail_url!

thumbnail_url = json_object.thumbnail_url
=> ""

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{ |a| a.attributes["type"] == "OriginalFile" }.first
=> #<Wistia::Media::Asset:0x007fa67caced68 @attributes={
    "width"=>640, "height"=>360, "fileSize"=>48442, "contentType"=>"video/mp4",
  }, @prefix_options={}, @persisted=false>
url = _.url
=> ""

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"
=> ""

Pretty fun, right?