youtube-transcript-api مكتبة Python مجانية ومفتوحة المصدر تجلب الترجمة المصاحبة لفيديو على YouTube: pip install youtube-transcript-api ثم YouTubeTranscriptApi().fetch(video_id). تعمل جيدًا من حاسوبك، لكن YouTube يحظرها غالبًا من الخوادم السحابية بالخطأ RequestBlocked أو IpBlocked، ولا تفيد مع الفيديوهات التي لا ترجمة لها.
شغّلناها من جهاز سحابي في 21 نوفمبر 2026، ثم مرّرنا الفيديوهين نفسيهما عبر واجهتنا المستضافة من الجهاز نفسه. هنا ما فعلته كل منهما، وكيف تستخدم المكتبة، ومتى تكون الواجهة المستضافة أنسب.
ما هي youtube-transcript-api؟
مكتبة Python من تطوير Jonas Depoix، منشورة على GitHub وPyPI بترخيص MIT. الإصدار الحالي 1.2.5، ويعمل مع Python 3.8 وما بعده.
- تقرأ الترجمات التي يملكها YouTube أصلًا، سواء ترجمة القناة نفسها أو الترجمة التلقائية.
- لا تحتاج إلى مفتاح API ولا إلى متصفح بلا واجهة.
- تعرض لغات الترجمة المتاحة للفيديو، وتفضّل لغة على أخرى، وتستخدم الترجمة الآلية في YouTube.
- تُخرج نصًا أو JSON أو SRT أو WebVTT، ولها أداة سطر أوامر.
يتحدث ملف README بصراحة عن المقايضة: فهي تستخدم جزءًا غير موثق من مشغّل YouTube على الويب، لذلك «no guarantee that it won't stop working tomorrow».
كيف أستخدمها؟
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
من سطر الأوامر، يقوم youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json بالشيء نفسه. يشرح README عرض اللغات والترجمة وغير ذلك.
لماذا تفشل بالخطأ IpBlocked على خادمي؟
لأن YouTube يحظر معظم الطلبات القادمة من مزودي الخدمات السحابية. يقول README المكتبة ذلك صراحة: YouTube «has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)»، لذلك ستواجه «most likely» أخطاء RequestBlocked أو IpBlocked بعد نشر الكود. وقد يُحظر عنوان IP المنزلي أيضًا بعد طلبات كثيرة.
رأينا ذلك بأنفسنا. في 21 نوفمبر 2026 ثبّتنا الإصدار 1.2.5 على جهاز سحابي وطلبنا محاضرتين عامتين:
الجهاز نفسه، الفيديوهان نفسهما، 21 نوفمبر 2026 (UTC).
أعطى الاستدعاءان IpBlocked بعد نحو 1.1 ثانية. وطلب عادي إلى youtube.com من ذلك الجهاز أُعيد توجيهه إلى صفحة Google الخاصة بـ«حركة المرور غير المعتادة»، أي أن YouTube هو من رفض الجهاز، لا خللًا في المكتبة.
الحل في README هو الوكلاء، ويوصي بوكلاء سكنية متناوبة لأن YouTube يحظر الوكلاء الثابتة بعد استخدام طويل. هذا ينجح، لكنه يعني خدمة مدفوعة أخرى وحسابًا آخر وحظرًا يجب مراقبته.
ما الذي قد يوقفها أيضًا؟
- لا ترجمة. المكتبة تقرأ الترجمات ولا تفرّغ الصوت. الترجمة المعطّلة تعطي
TranscriptsDisabled، واللغة الغائبة تعطيNoTranscriptFound. - الفيديوهات المقيّدة بالعمر. يقول README إن تسجيل الدخول عبر ملفات تعريف الارتباط، الذي تحتاجه هذه الفيديوهات، «currently not available» بعد تغييرات من جهة YouTube.
- تغييرات YouTube. لأنها تستخدم واجهة غير موثقة، قد يعطّلها تحديث من YouTube حتى يصدر إصدار جديد.
لا شيء من هذا سبب لتجنبها في برنامج على حاسوبك المحمول. لكنه سبب للتخطيط له قبل وضعها في منتج.
ماذا أستخدم بدلًا منها عند الحظر؟
واجهة API مستضافة للنصوص تتولى الجلب من جهتها. واجهتنا هي واجهة YouTubeTranscript.dev. من الجهاز السحابي نفسه، قبل ذلك ببضع دقائق، الفيديوهان نفسهما:
| الفيديو | المدة | الوقت | الكلمات | أسطر بطوابع زمنية | الأرصدة |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4.2 ثانية | 3,357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4.2 ثانية | 6,363 | 887 | 1 |
| فيديو 3Blue1Brown نفسه، مطلوب مرة أخرى | 18:40 | 1.3 ثانية | 3,357 | 286 | 0 |
كيف قِسنا: طلب واحد لكل فيديو إلى POST /api/v2/transcribe، الترجمة فقط مع الطوابع الزمنية، وقاس curl الوقت من الإرسال حتى الرد الكامل. الأرصدة هي ما أبلغ عنه كل رد. تجربة واحدة لكل منها، فاعتبر الأوقات أمثلة.
الاستدعاء من Python:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
المقايضة هي التكلفة: المكتبة مجانية، والواجهة تكلّف رصيدًا لكل فيديو مترجم، مع عشرة أرصدة مجانية شهريًا وخطط مدفوعة من 5 دولارات مقابل 500. ومع "mode": "auto" تفرّغ أيضًا الفيديوهات التي لا ترجمة لها، برصيد لكل دقيقتين من الصوت. وهناك حزمة Python SDK إن لم ترد كتابة الطلب بنفسك.
كيف أدمج واجهة API للتفريغ الصوتي في منتجي؟
النمط نفسه يصلح مع أي واجهة:
- احفظ المفتاح على الخادم. يرسل المستخدمون رابطًا إلى الخادم الخلفي، وهو يستدعي الواجهة. لا تضع المفتاح أبدًا في كود المتصفح أو التطبيق.
- اقبل أي صيغة للرابط. مرّر الرابط كما كتبه المستخدم؛ واجهتنا تقبل الروابط الكاملة وyoutu.be وShorts وروابط التضمين والمعرّفات المجردة (القائمة الكاملة).
- خزّن النص حسب معرّف الفيديو. معظم المنتجات تطلب الفيديوهات الشائعة نفسها مرارًا. عندنا، النص الذي يملكه حسابك لا يكلف شيئًا عند طلبه مجددًا، كما يُظهر السطر الثالث، لكن النسخة المحلية أسرع.
- عامل الفيديوهات بلا ترجمة كمهمة. تفريغ الصوت يستغرق وقتًا أطول مما ينبغي لطلب ويب أن ينتظره. أرسل
mode: "auto"معwebhook_url، أو استعلم دوريًا عن معرّف المهمة المُعاد، واعرض للمستخدم حالة التقدم. - استخدم الدفعات عند الكثرة. لقائمة تشغيل أو قناة أو تراكم، استخدم نقطة الدفعات بدل حلقة من الاستدعاءات المفردة، لتبقى ضمن حد المعدّل.
تشرح وثائق API كل حقل، ويقيس دليل واجهة تحويل الكلام إلى نص الدقة والتكلفة على صوت بلا ترجمة.
أيهما أستخدم؟
| إذا كنت... | استخدم |
|---|---|
| تشغّل برنامجًا على حاسوبك، بضعة فيديوهات في كل مرة | youtube-transcript-api |
| تنشر على خادم سحابي أو دالة بلا خادم أو منتج | واجهة API مستضافة، أو المكتبة مع وكلاء سكنية متناوبة |
| تتعامل مع فيديوهات بلا ترجمة | خدمة تفرّغ الصوت |
| تجلب قوائم تشغيل أو قنوات كاملة | واجهة API مستضافة بنقطة دفعات |
الخلاصة
- youtube-transcript-api مجانية وبترخيص MIT وسهلة:
YouTubeTranscriptApi().fetch(video_id). - على خادم سحابي يحظرها YouTube غالبًا؛ على جهازنا السحابي أعطى الفيديوهان
IpBlockedبعد نحو 1.1 ثانية. الحل المقترح هو الوكلاء. - تقرأ الترجمات الموجودة فقط، والفيديوهات المقيّدة بالعمر غير متاحة حاليًا.
- واجهة مستضافة أعادت الفيديوهين نفسيهما من الجهاز نفسه في 4.2 ثانية لكل منهما، برصيد واحد لكل منهما، وتتعامل مع الفيديوهات بلا ترجمة.
الأسئلة الشائعة
ما هي youtube-transcript-api؟+
مكتبة Python مفتوحة المصدر (ترخيص MIT) تجلب الترجمات المصاحبة الموجودة أصلًا لفيديو على YouTube، بما فيها التلقائية، بلا مفتاح API وبلا متصفح. ثبّتها بـ pip install youtube-transcript-api واستدعِ YouTubeTranscriptApi().fetch(video_id).
لماذا تعطي youtube-transcript-api الخطأ RequestBlocked أو IpBlocked؟+
لأن YouTube يحظر معظم الطلبات القادمة من عناوين IP لمزودي الخدمات السحابية، وقد يحظر أي عنوان يرسل طلبات كثيرة. يقول ذلك ملف README للمكتبة نفسه ويقترح وكلاء سكنية متناوبة. من خادمنا السحابي في 21 نوفمبر 2026 أعطى الفيديوهان اللذان جربناهما IpBlocked بعد نحو 1.1 ثانية.
هل تستطيع youtube-transcript-api تفريغ فيديو بلا ترجمة مصاحبة؟+
لا. هي تقرأ الترجمات الموجودة فقط. الفيديو الذي عُطّلت ترجمته يعطي TranscriptsDisabled، والفيديو الذي لا توجد فيه لغتك يعطي NoTranscriptFound. لاستخراج نص من الصوت تحتاج إلى خدمة تحويل الكلام إلى نص.
هل youtube-transcript-api مجانية؟+
نعم، المكتبة مجانية وبترخيص MIT. لكن تشغيلها على خادم يعني غالبًا دفع ثمن وكلاء، لأن عناوين IP السحابية محظورة.
ماذا أستخدم بدل youtube-transcript-api على الخادم؟+
واجهة API مستضافة للنصوص تتولى الجلب عنك. من الجهاز نفسه الذي حُظرت فيه المكتبة، أعادت واجهة YouTubeTranscript.dev الفيديوهين في 4.2 ثانية لكل منهما، برصيد واحد لكل منهما، وأعادت طلبًا مكررًا في 1.3 ثانية مجانًا.
كيف أدمج واجهة API للتفريغ الصوتي في منتجي؟+
احفظ مفتاح API على خادمك، وأرسل رابط الفيديو إلى نقطة نهاية واحدة، وخزّن النص حسب معرّف الفيديو حتى لا تدفع مرتين، وعامل الفيديوهات بلا ترجمة كمهمة غير متزامنة مع Webhook، واستخدم نقطة الدفعات للفيديوهات الكثيرة.