Getting a Vimeo video thumbnail using the ID or URL

15 April 2020

It should be easy to get an automatic thumbnail for your Vimeo videos, but if you have your videos set to private, it’s much more complex than it needs to be.

Luckily, there is a way to get a thumbnail WITHOUT fully integrating the API and authenticating yourself.

Note: Vimeo seem to change how these things work on a regular basis, presumably because they’d prefer it if all such requests went through the API. This is working as of 9th April 2020.

Update 15th April 2020
It seems that calling the API will sometimes return a subset of data, resulting in no URL to parse for an ID, which if you then just used the $image URL directly, would fetch the Vimeo striped ‘processing’ image rather than the thumbnail for your video.

I’ve factored this into my site by basically storing the ID I get back from parsing the API results, and using that. If I don’t have the ID stored for a particular video, it will run the code below to get it, then store it. This means that even if the API returns the subset of data at that point, it will keep on trying until the ID is returned, at which point it will be stored and the API will no longer be called.

You could easily add that as a background task, but for my purposes its easy enough to just do it dynamically when the image loads.


Note: PHP codes.

first, CURL one off. This is necessary so you can add the referral header in
which should be one of the domains that's whitelisted for your private video
(for me, it's just the domain of the site the script is running on)

If you're only getting basic data back, without the thumbnail_url, it's because
your referer isn't recognised as being whitelisted in vimeo, so you're only getting
back the basic information


$url = ''; //the full URL of your vimeo video

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://vimeo.com/api/oembed.json?url=".$url,
"Referer: ".$_SERVER['HTTP_REFERER'].""

$response = curl_exec($curl);
$err = curl_error($curl);

//this returns JSon so decode it into an object
$thumby = json_decode($response);

$thumbnail = $thumby->thumbnail_url;

//dirty parsing of the URL. Could be a regex of course!
//end result is the unique ID for that thumbnail
$thumbarr = explode('_',$thumbnail);
$thumbnail = str_replace('https://i.vimeocdn.com/video/', '', $thumbarr[0]);

//you can then use that ID to fetch better quality thumbs - the 640 is the width of the
//image you want.
$image = 'https://i.vimeocdn.com/video/'.$thumbnail.'_640.jpg';