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.



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



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!

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.


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

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

Now let's say we want a sideways Lenny 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"
=> ""

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?