YouTube Thumbnail Extractor API

Overview

The YouTube Thumbnail Extractor API enables you to instantly extract thumbnail URLs from any YouTube video or Short in all available resolutions. Lightning-fast with zero processing time, perfect for developers building video platforms, content management systems, and media applications.

Base URL: https://youtube-thumbnails-extractor-api.p.rapidapi.com

Features

Extract thumbnail URLs from any public YouTube video
Works with regular videos AND YouTube Shorts
All 5 resolution sizes (120x90 to 1280x720)
Lightning-fast response (sub-10ms average)
Direct CDN URLs from YouTube
Zero processing required
Complete metadata with dimensions

Authentication

All requests must include your RapidAPI key in the headers:

x-rapidapi-key: YOUR_RAPIDAPI_KEY
x-rapidapi-host: youtube-thumbnails-extractor-api.p.rapidapi.com

Quick Start Examples

Example 1: Regular Video - All Resolutions

curl -X GET "https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-rapidapi-host: youtube-thumbnails-extractor-api.p.rapidapi.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"

Response:

{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "processing_time_ms": 3,
  "thumbnails": {
    "maxresdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "width": 1280,
      "height": 720
    },
    "sddefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg",
      "width": 640,
      "height": 480
    },
    "hqdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "mqdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
      "width": 320,
      "height": 180
    },
    "default": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg",
      "width": 120,
      "height": 90
    }
  }
}

Example 2: YouTube Short

curl -X GET "https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=https://www.youtube.com/shorts/IGZS3P8cqhY" \
  -H "x-rapidapi-host: youtube-thumbnails-extractor-api.p.rapidapi.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"

Response:

{
  "success": true,
  "video_id": "IGZS3P8cqhY",
  "video_url": "https://www.youtube.com/watch?v=IGZS3P8cqhY",
  "processing_time_ms": 2,
  "thumbnails": {
    "maxresdefault": {
      "url": "https://i.ytimg.com/vi/IGZS3P8cqhY/maxresdefault.jpg",
      "width": 1280,
      "height": 720
    },
    "sddefault": {
      "url": "https://i.ytimg.com/vi/IGZS3P8cqhY/sddefault.jpg",
      "width": 640,
      "height": 480
    },
    "hqdefault": {
      "url": "https://i.ytimg.com/vi/IGZS3P8cqhY/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "mqdefault": {
      "url": "https://i.ytimg.com/vi/IGZS3P8cqhY/mqdefault.jpg",
      "width": 320,
      "height": 180
    },
    "default": {
      "url": "https://i.ytimg.com/vi/IGZS3P8cqhY/default.jpg",
      "width": 120,
      "height": 90
    }
  }
}

Example 3: Short URL Format (youtu.be)

curl -X GET "https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=https://youtu.be/87NEZG6E3yk" \
  -H "x-rapidapi-host: youtube-thumbnails-extractor-api.p.rapidapi.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"

Response:

{
  "success": true,
  "video_id": "87NEZG6E3yk",
  "video_url": "https://www.youtube.com/watch?v=87NEZG6E3yk",
  "processing_time_ms": 4,
  "thumbnails": {
    "maxresdefault": {
      "url": "https://i.ytimg.com/vi/87NEZG6E3yk/maxresdefault.jpg",
      "width": 1280,
      "height": 720
    },
    "sddefault": {
      "url": "https://i.ytimg.com/vi/87NEZG6E3yk/sddefault.jpg",
      "width": 640,
      "height": 480
    },
    "hqdefault": {
      "url": "https://i.ytimg.com/vi/87NEZG6E3yk/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "mqdefault": {
      "url": "https://i.ytimg.com/vi/87NEZG6E3yk/mqdefault.jpg",
      "width": 320,
      "height": 180
    },
    "default": {
      "url": "https://i.ytimg.com/vi/87NEZG6E3yk/default.jpg",
      "width": 120,
      "height": 90
    }
  }
}

Endpoints

API Information

GET /

Get API information and usage instructions.

Response:

{
  "name": "YouTube Thumbnail Extractor API",
  "version": "1.0.0",
  "description": "Extract thumbnail URLs from any YouTube video in all available resolutions.",
  "endpoints": {
    "GET /thumbnails": "Get thumbnail URLs from YouTube video (use query parameter: ?url=VIDEO_URL)",
    "GET /health": "Health check"
  },
  "resolutions": [
    "maxresdefault (1280x720)",
    "sddefault (640x480)",
    "hqdefault (480x360)",
    "mqdefault (320x180)",
    "default (120x90)"
  ],
  "example": {
    "method": "GET",
    "endpoint": "/thumbnails?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

Health Check

GET /health

Check if the API is operational.

Response:

{
  "status": "ok",
  "timestamp": 1704067200000
}

Extract Thumbnails

GET /thumbnails

Extract all available thumbnail URLs from a YouTube video or Short.

Query Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	Full YouTube video URL (supports regular videos and Shorts)

Successful Response (200 OK):

{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "processing_time_ms": 3,
  "thumbnails": {
    "maxresdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "width": 1280,
      "height": 720
    },
    "sddefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg",
      "width": 640,
      "height": 480
    },
    "hqdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "mqdefault": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
      "width": 320,
      "height": 180
    },
    "default": {
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg",
      "width": 120,
      "height": 90
    }
  }
}

Response Fields:

Field	Type	Description
`success`	boolean	Whether the request was successful
`video_id`	string	YouTube video ID
`video_url`	string	Standard YouTube watch URL
`processing_time_ms`	integer	Processing time in milliseconds
`thumbnails`	object	Object containing all thumbnail resolutions
`thumbnails.maxresdefault`	object	Highest resolution (1280x720)
`thumbnails.sddefault`	object	Standard definition (640x480)
`thumbnails.hqdefault`	object	High quality (480x360)
`thumbnails.mqdefault`	object	Medium quality (320x180)
`thumbnails.default`	object	Default size (120x90)

Thumbnail Resolutions

maxresdefault (1280x720)

Highest quality thumbnail, perfect for large displays and hero images.

Width: 1280px
Height: 720px
Use case: Hero images, full-width banners, desktop displays

sddefault (640x480)

Standard definition, ideal for medium-sized previews.

Width: 640px
Height: 480px
Use case: Card layouts, medium previews, tablet displays

hqdefault (480x360)

High quality thumbnail, great for card layouts and grids.

Width: 480px
Height: 360px
Use case: Grid layouts, video cards, small previews

mqdefault (320x180)

Medium quality, optimized for mobile devices.

Width: 320px
Height: 180px
Use case: Mobile displays, compact lists, thumbnails

default (120x90)

Small thumbnail, perfect for compact lists and notifications.

Width: 120px
Height: 90px
Use case: Lists, notifications, minimal UI elements

Supported YouTube URL Formats

The API accepts various YouTube URL formats:

https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/shorts/VIDEO_ID
https://www.youtube.com/embed/VIDEO_ID
https://www.youtube.com/v/VIDEO_ID

Error Responses

400 Bad Request

Missing URL:

{
  "error": "URL is required as query parameter: ?url=VIDEO_URL"
}

Invalid YouTube URL:

{
  "error": "Invalid YouTube URL"
}

401 Unauthorized

Missing or Invalid API Key:

{
  "error": "Unauthorized"
}

500 Internal Server Error

Unexpected Error:

{
  "success": false,
  "error": "Unknown error occurred",
  "video_id": "dQw4w9WgXcQ"
}

Pricing Plans

Basic (Free)

Perfect for testing and small projects

Price: $0/month
Monthly Requests: 100 (Hard Limit)
Rate Limit: 30 requests/minute
Support: Community

Pro

Ideal for individual developers

Price: $4.99/month
Monthly Requests: 100,000 (Hard Limit)
Rate Limit: 50 requests/minute
Support: Email

Ultra

Best for growing businesses

Price: $14.99/month
Monthly Requests: 900,000 (Hard Limit)
Rate Limit: 60 requests/minute
Support: Priority Email

Mega

Enterprise-grade solution

Price: $39.99/month
Monthly Requests: 1,800,000 (Hard Limit)
Rate Limit: 100 requests/minute
Support: Priority Email + Dedicated Support

Rate Limiting

The API enforces rate limits based on your subscription plan. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Rate Limit Headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704070800

Best Practices

1. URL Encoding

Always encode the YouTube URL parameter:

const videoUrl = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
const apiUrl = `https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=${encodeURIComponent(videoUrl)}`;

2. Cache Results

Cache thumbnail URLs to avoid redundant API calls for the same video. Thumbnails rarely change.

3. Handle Errors Gracefully

Always implement error handling for invalid URLs or network issues.

try {
  const response = await fetch(apiUrl, {
    headers: {
      'x-rapidapi-key': 'YOUR_KEY',
      'x-rapidapi-host': 'youtube-thumbnails-extractor-api.p.rapidapi.com'
    }
  });

  const data = await response.json();

  if (!data.success) {
    console.error('Error:', data.error);
  }
} catch (error) {
  console.error('Network error:', error);
}

4. Validate URLs Before Sending

Verify YouTube URLs client-side before making API requests to save quota.

5. Choose Appropriate Resolution

Select the resolution that matches your use case:

maxresdefault for hero images and large displays
sddefault for medium cards and previews
hqdefault for grid layouts
mqdefault for mobile displays
default for small lists and notifications

6. Fallback Strategy

Implement a fallback for maxresdefault since it may not always be available:

function getBestThumbnail(thumbnails) {
  return thumbnails.maxresdefault?.url ||
         thumbnails.sddefault?.url ||
         thumbnails.hqdefault?.url;
}

Code Examples

JavaScript (Fetch)

async function getThumbnails(videoUrl) {
  const apiUrl = `https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=${encodeURIComponent(videoUrl)}`;

  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'x-rapidapi-key': 'YOUR_RAPIDAPI_KEY',
      'x-rapidapi-host': 'youtube-thumbnails-extractor-api.p.rapidapi.com'
    }
  });

  const data = await response.json();

  if (data.success) {
    console.log(`Video ID: ${data.video_id}`);
    console.log(`Max resolution: ${data.thumbnails.maxresdefault.url}`);
    return data.thumbnails;
  } else {
    throw new Error(data.error);
  }
}

getThumbnails('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
  .then(thumbnails => {
    console.log('All thumbnails:', thumbnails);
  })
  .catch(error => console.error(error));

Python (Requests)

import requests

def get_thumbnails(video_url):
    url = f'https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url={video_url}'

    headers = {
        'x-rapidapi-key': 'YOUR_RAPIDAPI_KEY',
        'x-rapidapi-host': 'youtube-thumbnails-extractor-api.p.rapidapi.com'
    }

    response = requests.get(url, headers=headers)
    data = response.json()

    if data.get('success'):
        print(f"Video ID: {data['video_id']}")
        print(f"Max resolution: {data['thumbnails']['maxresdefault']['url']}")
        return data['thumbnails']
    else:
        raise Exception(data.get('error', 'Unknown error'))

thumbnails = get_thumbnails('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
print(thumbnails)

Node.js (Axios)

const axios = require('axios');

async function getThumbnails(videoUrl) {
  try {
    const url = `https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=${encodeURIComponent(videoUrl)}`;

    const response = await axios.get(url, {
      headers: {
        'x-rapidapi-key': 'YOUR_RAPIDAPI_KEY',
        'x-rapidapi-host': 'youtube-thumbnails-extractor-api.p.rapidapi.com'
      }
    });

    if (response.data.success) {
      console.log(`Video ID: ${response.data.video_id}`);
      console.log(`Processing time: ${response.data.processing_time_ms}ms`);
      return response.data.thumbnails;
    }
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

getThumbnails('https://www.youtube.com/shorts/IGZS3P8cqhY')
  .then(thumbnails => {
    console.log('High quality URL:', thumbnails.hqdefault.url);
  })
  .catch(console.error);

PHP

<?php

function getThumbnails($videoUrl) {
    $url = "https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=" . urlencode($videoUrl);

    $headers = [
        'x-rapidapi-key: YOUR_RAPIDAPI_KEY',
        'x-rapidapi-host: youtube-thumbnails-extractor-api.p.rapidapi.com'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);

    if ($data['success']) {
        echo "Video ID: {$data['video_id']}\n";
        echo "Max resolution: {$data['thumbnails']['maxresdefault']['url']}\n";
        return $data['thumbnails'];
    } else {
        throw new Exception($data['error']);
    }
}

$thumbnails = getThumbnails('https://www.youtube.com/watch?v=87NEZG6E3yk');
print_r($thumbnails);
?>

Ruby

require 'net/http'
require 'json'
require 'uri'

def get_thumbnails(video_url)
  encoded_url = URI.encode_www_form_component(video_url)
  url = URI("https://youtube-thumbnails-extractor-api.p.rapidapi.com/thumbnails?url=#{encoded_url}")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request['x-rapidapi-key'] = 'YOUR_RAPIDAPI_KEY'
  request['x-rapidapi-host'] = 'youtube-thumbnails-extractor-api.p.rapidapi.com'

  response = http.request(request)
  data = JSON.parse(response.body)

  if data['success']
    puts "Video ID: #{data['video_id']}"
    puts "Max resolution: #{data['thumbnails']['maxresdefault']['url']}"
    return data['thumbnails']
  else
    raise StandardError, data['error']
  end
end

thumbnails = get_thumbnails('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
puts thumbnails.inspect

Use Cases

Video Platforms

Display thumbnails for embedded videos
Create video galleries and playlists
Build video preview interfaces

Content Management Systems

Auto-fetch thumbnails when users paste YouTube links
Create video archives with previews
Manage video collections

Generate preview cards for shared videos
Create video sharing features
Build content schedulers with thumbnails

Mobile Applications

Display video thumbnails efficiently
Create video libraries with appropriate sizes
Optimize bandwidth with resolution selection

SEO & Marketing

Extract thumbnails for meta tags
Create rich snippets for social sharing
Optimize Open Graph images

E-learning Platforms

Display course video previews
Create lesson thumbnails
Build searchable video libraries

FAQ

Q: Do I need to URL-encode the YouTube URL?
A: Yes, it’s recommended to use encodeURIComponent() in JavaScript or equivalent in other languages to properly encode the URL.

Q: Are all resolutions always available?
A: maxresdefault may not be available for all videos. Videos uploaded in HD (720p or higher) typically have this resolution. All other resolutions are always available.

Q: Does it work with YouTube Shorts?
A: Yes! The API works with both regular YouTube videos and YouTube Shorts.

Q: How fast is the API?
A: Extremely fast. Average response time is under 10ms since we only construct URLs without any processing.

Q: Can I use the thumbnail URLs directly in my application?
A: Yes! All URLs are direct CDN links from YouTube that you can use immediately in img tags or anywhere else.

Q: Do the thumbnail URLs expire?
A: YouTube thumbnail URLs are permanent and do not expire as long as the video exists.

Q: Can I use this for commercial projects?
A: Yes, all plans can be used for commercial purposes according to our terms of service.

Q: Do you support unlisted videos?
A: Yes, as long as you have the video URL, the API can extract thumbnail URLs for public and unlisted videos.

Q: Why is there a processing_time_ms field if there’s no processing?
A: This field measures the total API response time including network overhead, useful for monitoring and debugging.

Support

Need help? We’re here for you:

Email: support@cliperly.com

Terms of Use

By using this API, you agree to:

Use the service only through RapidAPI
Not exceed your plan’s rate limits
Not abuse or attempt to bypass restrictions
Comply with YouTube’s Terms of Service
Use thumbnail URLs in accordance with copyright laws

Last updated: October 2025

YouTube Thumbnail Extractor API

Overview

Features

Authentication

Quick Start Examples

Example 1: Regular Video - All Resolutions

Example 2: YouTube Short

Example 3: Short URL Format (youtu.be)

Endpoints

API Information

Health Check

Extract Thumbnails

Thumbnail Resolutions

maxresdefault (1280x720)

sddefault (640x480)

hqdefault (480x360)

mqdefault (320x180)

default (120x90)

Supported YouTube URL Formats

Error Responses

400 Bad Request

401 Unauthorized

500 Internal Server Error

Pricing Plans

Basic (Free)

Pro

Ultra

Mega

Rate Limiting

Best Practices

1. URL Encoding

2. Cache Results

3. Handle Errors Gracefully

4. Validate URLs Before Sending

5. Choose Appropriate Resolution

6. Fallback Strategy

Code Examples

JavaScript (Fetch)

Python (Requests)

Node.js (Axios)

PHP

Ruby

Use Cases

Video Platforms

Content Management Systems

Social Media Tools

Mobile Applications

SEO & Marketing

E-learning Platforms

FAQ

Support

Terms of Use