YouTube API: كيفية الحصول على صورة مصغرة للفيديو وتجنب الأخطاء الشائعة

YouTube API: كيفية الحصول على صورة مصغرة للفيديو وتجنب الأخطاء الشائعة

هل سبق لك أن حاولت استخراج صورة من YouTube وحصلت على رابط معطل، أو شاشة فارغة، أو الأسوأ من ذلك — "403 Forbidden"؟ إذا كان الأمر كذلك، فأنت لست وحدك. السؤال "How do I get a YouTube video thumbnail from the YouTube API?" حصد آلاف المشاهدات وعشرات الإجابات على Stack Overflow، نصفها قديم أو خطير صراحة.

في هذه المقالة، سنحلل الأخطاء الحقيقية التي يرتكبها حتى مطوري PHP ذوي الخبرة، ونوضح كيفية تجنبها. ستتعلم ليس فقط "كيف تفعل"، بل لماذا يعمل حل بينما لا يعمل الآخر. هيا بنا!

لماذا لا يعمل مجرد نسخ الرابط؟

أشهر إجابة على Stack Overflow تقترح استخدام النمط التالي:

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

يبدو الأمر بسيطًا: تأخذ معرف الفيديو من الرابط، تضعه — وتنتهي. لكن في الواقع، ستواجه على الأرجح إحدى هذه المشكلات:

• رابط معطل — بالنسبة للفيديوهات القديمة أو فيديوهات Shorts، قد تكون الصورة المصغرة غير موجودة.
• HTTP 403 — YouTube يحظر الطلبات المباشرة بدون الرؤوس الصحيحة.
• جودة منخفضة — maxresdefault.jpg ليس متاحًا دائمًا، وقد تحصل على 120×90 بكسل.
• مشاكل التخزين المؤقت — إذا تم تحميل الفيديو للتو، قد تظهر الصورة المصغرة بعد 10–15 دقيقة.

دعنا نحلل كل خطأ ونقدم حلاً عمليًا بلغة PHP.

الخطأ رقم 1: الثقة العمياء بالرابط القياسي

يكتب العديد من المطورين بهذه الطريقة:

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.