YouTube API: как получить превью видео и не наступить на грабли

YouTube API: как получить превью видео и не наступить на грабли

Вы когда-нибудь пытались вытащить картинку из YouTube, а получали битую ссылку, пустой экран или — что ещё обиднее — «403 Forbidden»? Если да, то вы не одиноки. Вопрос «How do I get a YouTube video thumbnail from the YouTube API?» собрал на Stack Overflow тысячи просмотров и десятки ответов, половина из которых — устаревшие или откровенно опасные.

В этой статье мы разберём реальные ошибки, которые совершают даже опытные PHP-разработчики, и покажем, как их обойти. Вы узнаете не просто «как сделать», а почему одно решение работает, а другое — нет. Поехали!

Почему простое копирование URL не работает?

Самый популярный ответ на Stack Overflow предлагает использовать шаблон:

https://img.youtube.com/vi/{VIDEO_ID}/maxresdefault.jpg

Казалось бы, берёшь ID видео из URL, подставляешь — и готово. Но на практике вы наверняка столкнётесь с одной из этих проблем:

• Битая ссылка — для старых видео или видео в формате Shorts превью может отсутствовать.
• HTTP 403 — YouTube блокирует прямые запросы без правильных заголовков.
• Маленькое качество — maxresdefault.jpg не всегда доступен, и вы получаете 120×90 пикселей.
• Проблемы с кэшированием — если видео только загружено, превью может появиться через 10–15 минут.

Давайте разберём каждую ошибку и предложим работающее решение на PHP.

Ошибка №1: Слепое доверие стандартному URL

Многие разработчики пишут так:

function getThumbnail($videoId) {
    return "https://img.youtube.com/vi/{$videoId}/maxresdefault.jpg";
}

Это работает только в 70% случаев. Для остальных 30% вы получите либо заглушку, либо ошибку.

Правильное решение: проверять доступность

Вместо того чтобы надеяться на удачу, используйте get_headers() или cURL. Вот пример с cURL:

function getAvailableThumbnail($videoId) {
    $qualities = [
        'maxresdefault.jpg',
        'sddefault.jpg',
        'hqdefault.jpg',
        'mqdefault.jpg',
        'default.jpg'
    ];

    $baseUrl = "https://img.youtube.com/vi/{$videoId}/";

    foreach ($qualities as $quality) {
        $url = $baseUrl . $quality;
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_NOBODY, true);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode === 200) {
            return $url;
        }
    }

    return null; // если ничего не нашлось
}

// Использование
$thumbnail = getAvailableThumbnail('dQw4w9WgXcQ');
echo $thumbnail; // https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg

Этот код перебирает все возможные размеры и возвращает первый доступный. Он решает проблему с отсутствием maxresdefault — если его нет, возьмётся hqdefault или даже default.

Ошибка №2: Игнорирование HTTP-заголовков

Прямой запрос к img.youtube.com часто приводит к 403 ошибке, особенно если ваш сервер находится за прокси или использует старую версию PHP. YouTube проверяет заголовок Referer и User-Agent.

Как это исправить?

Добавьте правильные заголовки в cURL-запрос:

function getThumbnailWithHeaders($videoId) {
    $url = "https://img.youtube.com/vi/{$videoId}/hqdefault.jpg";

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
        'Referer: https://www.youtube.com/'
    ]);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // для локальной разработки

    $imageData = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        return $imageData; // возвращаем бинарные данные
    }

    return false;
}

// Сохраняем изображение
$image = getThumbnailWithHeaders('dQw4w9WgXcQ');
if ($image) {
    file_put_contents('thumbnail.jpg', $image);
    echo 'OK';
} else {
    echo 'Ошибка загрузки';
}

Важно: Заголовок Referer должен указывать на YouTube. Без него многие CDN-сервера Google блокируют запрос.

Ошибка №3: Работа с YouTube Data API v3 без кэширования

Альтернативный способ — использовать официальный API. Но многие совершают фатальную ошибку: делают запрос к API при каждом обращении к странице. Это быстро исчерпывает квоту (10 000 единиц в день для бесплатного аккаунта).

Пример неправильного подхода:

// ПЛОХО: запрос к API при каждом заходе
function getThumbnailFromAPI($videoId) {
    $apiKey = 'YOUR_API_KEY';
    $url = "https://www.googleapis.com/youtube/v3/videos?id={$videoId}&part=snippet&key={$apiKey}";
    $response = file_get_contents($url);
    $data = json_decode($response, true);
    return $data['items'][0]['snippet']['thumbnails']['high']['url'];
}

Если у вас 1000 посетителей в день — вы сожжёте квоту за пару часов.

Правильное решение: кэширование + ресайз

Вот пример с кэшированием в файл и использованием API только один раз для каждого видео:

function getCachedThumbnail($videoId, $apiKey) {
    $cacheDir = __DIR__ . '/cache/';
    $cacheFile = $cacheDir . md5($videoId) . '.jpg';
    $cacheTime = 86400; // 24 часа

    // Проверяем кэш
    if (file_exists($cacheFile) && (time() - filemtime($cacheFile) < $cacheTime)) {
        return file_get_contents($cacheFile);
    }

    // Запрашиваем через API
    $apiUrl = "https://www.googleapis.com/youtube/v3/videos?id={$videoId}&part=snippet&key={$apiKey}";
    $response = file_get_contents($apiUrl);
    $data = json_decode($response, true);

    if (!isset($data['items'][0]['snippet']['thumbnails'])) {
        return false; // видео не найдено
    }

    // Берём лучшее доступное качество
    $qualities = ['maxres', 'standard', 'high', 'medium', 'default'];
    $thumbnailUrl = null;
    foreach ($qualities as