Categories
curl php youtube youtube-api youtube-data-api

How do I get a YouTube video thumbnail from the YouTube API?

2698

If I have a YouTube video URL, is there any way to use PHP and cURL to get the associated thumbnail from the YouTube API?

1

5188

Each YouTube video has four generated images. They are predictably formatted as follows:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/0.jpg
https://img.youtube.com/vi/<insert-youtube-video-id-here>/1.jpg
https://img.youtube.com/vi/<insert-youtube-video-id-here>/2.jpg
https://img.youtube.com/vi/<insert-youtube-video-id-here>/3.jpg

The first one in the list is a full size image and others are thumbnail images. The default thumbnail image (i.e., one of 1.jpg, 2.jpg, 3.jpg) is:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/default.jpg

For the high quality version of the thumbnail use a URL similar to this:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/hqdefault.jpg

There is also a medium quality version of the thumbnail, using a URL similar to the HQ:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/mqdefault.jpg

For the standard definition version of the thumbnail, use a URL similar to this:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/sddefault.jpg

For the maximum resolution version of the thumbnail use a URL similar to this:

https://img.youtube.com/vi/<insert-youtube-video-id-here>/maxresdefault.jpg

All of the above URLs are available over HTTP too. Additionally, the slightly shorter hostname i3.ytimg.com works in place of img.youtube.com in the example URLs above.

Alternatively, you can use the YouTube Data API (v3) to get thumbnail images.

20

  • 48

    Just in case anyone else makes this dumb mistake – you can’t use http://www.img.youtube.com, only http://img.youtube.com

    Nov 5, 2013 at 15:04


  • 13

    sddefault.jpg and maxresdefault.jpg formats are no longer working

    – clami219

    Mar 31, 2015 at 9:27


  • 7

    @munissor that is NOT TRUE, 0.jpg IS NOT ALWAYS fullsize version… It might be, but it is not a rule…

    – jave.web

    Apr 14, 2015 at 7:42


  • 9

    @jave.web @clami219 Since the sddefault and maxresdefault are not always available . Does the mqdefault works for all videos? What is the best URL to get thumbnail without the 2 black boders (at the top and the bottom)?

    – Ne AS

    Nov 9, 2016 at 11:32

  • 11

    If someone is wondering how to get sizes for not default: I just tried (and it actually works) that format names work as prefix. So you can get maxres2.jpg, hq2.jpg, hq3.jpg, etc.

    – Hernan

    Feb 9, 2019 at 17:33

427

You can use YouTube Data API to retrieve video thumbnails, caption, description, rating, statistics and more. API version 3 requires a key*. Obtain the key and create a videos: list request:

https://www.googleapis.com/youtube/v3/videos?key=YOUR_API_KEY&part=snippet&id=VIDEO_ID

Example PHP Code

$data = file_get_contents("https://www.googleapis.com/youtube/v3/videos?key=YOUR_API_KEY&part=snippet&id=T0Jqdjbed40");
$json = json_decode($data);
var_dump($json->items[0]->snippet->thumbnails);

Output

object(stdClass)#5 (5) {
  ["default"]=>
  object(stdClass)#6 (3) {
    ["url"]=>
    string(46) "https://i.ytimg.com/vi/T0Jqdjbed40/default.jpg"
    ["width"]=>
    int(120)
    ["height"]=>
    int(90)
  }
  ["medium"]=>
  object(stdClass)#7 (3) {
    ["url"]=>
    string(48) "https://i.ytimg.com/vi/T0Jqdjbed40/mqdefault.jpg"
    ["width"]=>
    int(320)
    ["height"]=>
    int(180)
  }
  ["high"]=>
  object(stdClass)#8 (3) {
    ["url"]=>
    string(48) "https://i.ytimg.com/vi/T0Jqdjbed40/hqdefault.jpg"
    ["width"]=>
    int(480)
    ["height"]=>
    int(360)
  }
  ["standard"]=>
  object(stdClass)#9 (3) {
    ["url"]=>
    string(48) "https://i.ytimg.com/vi/T0Jqdjbed40/sddefault.jpg"
    ["width"]=>
    int(640)
    ["height"]=>
    int(480)
  }
  ["maxres"]=>
  object(stdClass)#10 (3) {
    ["url"]=>
    string(52) "https://i.ytimg.com/vi/T0Jqdjbed40/maxresdefault.jpg"
    ["width"]=>
    int(1280)
    ["height"]=>
    int(720)
  }
}

* Not only that you need a key, you might be asked for billing information depending on the number of API requests you plan to make. However, few thousand requests per day are free.

Source article.

5

  • 6

    FYI: i did not change the code to fit the new JSON structure. The code in your getJSON is wrong. You used jsonc instead of json for getJSON. It’s failing because of your wrong JSON structure.

    – mauris

    Jun 24, 2012 at 7:41

  • 5

    Only the first example can use jsonc. The jQuery and PHP examples MUST use json. And I have updated the code to conform to the new JSON structure. I am using the code right now and it’s working LIVE. so don’t say it’s not working without reading the changes. Thanks!

    – mauris

    Jun 24, 2012 at 7:44

  • 7

    The jQuery and PHP examples MUST use json… can you provide a reference? Also, requesting a specific API version number (v=2) takes care of API changes.

    – Salman A

    Jun 24, 2012 at 7:47


  • 4

    The gdata call does not return whether maxresdefault.jpg is available for videos where it is available, only mq/hq/sd.

    – Aaron

    May 20, 2013 at 18:56

  • 2

    API v3 is VERY badly documented. They give you sample code but the “reference” section is very short of detail. Some things that should be relatively “obvious” seem to require extreme workarounds.

    – CashCow

    Feb 3, 2015 at 9:51

318

What Asaph said is right. However, not every YouTube video contains all nine
thumbnails. Also, the thumbnails’ image sizes depends on the video (the numbers
below are based on one). There are some thumbnails guaranteed to exist:

Width | Height | URL
------|--------|----
120   | 90     | https://i.ytimg.com/vi/<VIDEO ID>/1.jpg
120   | 90     | https://i.ytimg.com/vi/<VIDEO ID>/2.jpg
120   | 90     | https://i.ytimg.com/vi/<VIDEO ID>/3.jpg
120   | 90     | https://i.ytimg.com/vi/<VIDEO ID>/default.jpg
320   | 180    | https://i.ytimg.com/vi/<VIDEO ID>/mq1.jpg
320   | 180    | https://i.ytimg.com/vi/<VIDEO ID>/mq2.jpg
320   | 180    | https://i.ytimg.com/vi/<VIDEO ID>/mq3.jpg
320   | 180    | https://i.ytimg.com/vi/<VIDEO ID>/mqdefault.jpg
480   | 360    | https://i.ytimg.com/vi/<VIDEO ID>/0.jpg
480   | 360    | https://i.ytimg.com/vi/<VIDEO ID>/hq1.jpg
480   | 360    | https://i.ytimg.com/vi/<VIDEO ID>/hq2.jpg
480   | 360    | https://i.ytimg.com/vi/<VIDEO ID>/hq3.jpg
480   | 360    | https://i.ytimg.com/vi/<VIDEO ID>/hqdefault.jpg

Additionally, the some other thumbnails may or may not exist. Their presence is
probably based on whether the video is high-quality.

Width | Height | URL
------|--------|----
640   | 480    | https://i.ytimg.com/vi/<VIDEO ID>/sd1.jpg
640   | 480    | https://i.ytimg.com/vi/<VIDEO ID>/sd2.jpg
640   | 480    | https://i.ytimg.com/vi/<VIDEO ID>/sd3.jpg
640   | 480    | https://i.ytimg.com/vi/<VIDEO ID>/sddefault.jpg
1280  | 720    | https://i.ytimg.com/vi/<VIDEO ID>/hq720.jpg
1920  | 1080   | https://i.ytimg.com/vi/<VIDEO ID>/maxresdefault.jpg

You can find JavaScript and PHP scripts to retrieve thumbnails and other
YouTube information in:

You can also use the YouTube Video Information Generator tool to get all
the information about a YouTube video by submitting a URL or video id.

4

  • 5

    You can also achieve same result with official youtube link img.youtube.com/vi/mJ8tq8AnNis/mqdefault.jpg where mJ8tq8AnNis is video id

    – Ragaisis

    Oct 7, 2014 at 8:23


  • 5

    The tool “YouTube Video Information Generator” is currently not working. Consider editing the answer.

    Mar 22, 2017 at 22:57

  • 1

    Suggest removing all three links. None of them produce anything useful that I could see.

    – Bob Stein

    Mar 1, 2020 at 15:11

  • FWIW, the YouTube frontend hardcodes mqdefault.jpg to be 320×180

    Nov 23, 2021 at 7:34