كيف تحصل على نص فيديو يوتيوب عبر واجهة برمجية (curl وPython وJavaScript)

للحصول على نص فيديو يوتيوب عبر واجهة برمجية، أرسل طلب HTTP واحدًا يتضمن رابط الفيديو أو معرّفه ومفتاح الواجهة، ثم اقرأ النص من الاستجابة. يعرض هذا الدليل الطلب بلغات curl وPython وJavaScript باستخدام واجهة النصوص من sum.video، ثم يتناول الصيغ والأخطاء والتكاليف.

ما الذي تعيده الواجهة

تعيد نقطة الاتصال الترجمات النصية الموجودة لفيديو عام على يوتيوب، سواء كتبها صاحب الفيديو أو أنشأها يوتيوب تلقائيًا. هي لا تحوّل الصوت إلى نص. إذا لم تكن للفيديو ترجمات نصية، تحصل على خطأ بدل تخمين (المزيد أدناه).

الأساسيات:

• نقطة الاتصال: POST https://sum.video/api/v1/transcript (ويعمل GET أيضًا)
• المصادقة: مفتاحك في الترويسة X-API-Key، أو Authorization: Bearer <key>
• المدخلات: url أو video_id
• lang اختياري (الافتراضي en)
• format اختياري: json أو text أو srt

تذكر الاستجابة أيضًا اللغة الفعلية لمسار الترجمة وما إذا كان مُنشأً تلقائيًا، فتعرف الجودة التي يمكن توقعها.

الخطوة 1: أنشئ مفتاح الواجهة

سجّل الدخول وأنشئ مفتاحًا من لوحة الواجهة (/dashboard/api على sum.video). يمكنك امتلاك ما يصل إلى 5 مفاتيح نشطة، وهذا مفيد للفصل بين مفتاح الاختبار ومفتاح الإنتاج. يأتي مفتاحك الأول مع 10 أرصدة مجانية تكفي لـ 5 نصوص، فيمكنك تجربة كل ما يلي دون تكلفة.

الخطوة 2: أرسل طلبك الأول

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

بما أن GET يعمل أيضًا، يمكنك الاختبار من نص برمجي يكتفي ببناء الروابط. يفضَّل تمرير المفتاح في الترويسة حتى لا يظهر في السجلات.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (‏Node 18+ أو المتصفح)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

احتفظ بالمفتاح على خادم. المفتاح الموضوع في شيفرة المتصفح يمكن لأي شخص ينسخه بفتح أدوات المطوّر.

الخطوة 3: اختر الصيغة المناسبة

إذا كنت تنوي الربط بلحظة في الفيديو، فاستخدم json وابنِ الرابط من offset المقطع. وللتغذية إلى نموذج لغوي، يكون text أصغر وأبسط. وإذا أردت لاحقًا البحث يدويًا داخل نص ما، فراجع كيف تبحث داخل نص فيديو يوتيوب.

الخطوة 4: اختر اللغة

القيمة الافتراضية لـ lang هي en. اضبطها على اللغة التي تريدها، مثل de أو es. تبلغ الاستجابة عن لغة المسار الذي أُعيد فعلًا، فتحقق منها بدل أن تفترض. كثيرًا ما يكون للفيديو مسار ترجمة واحد فقط، والواجهة تعيد ترجمات حقيقية، فهي لا تترجمها لك.

الخطوة 5: تعامل مع الأخطاء

خطّط لهذه الحالات منذ اليوم الأول:

• 404 no_transcript: لا توجد للفيديو ترجمات، أو هو بث مباشر أو فيديو خاص أو محذوف. لا فائدة من إعادة المحاولة. تجاوزه أو اطلب من المستخدم فيديو آخر.
• 402 budget_exceeded: بلغت حد الأرصدة الشهري الذي ضبطته. انظر القسم التالي.
• حد المعدل: يسمح كل مفتاح بـ 60 طلبًا في الدقيقة. باعد بين المهام الدفعية وتمهّل عند تقييدك.
• أعطال من جانبنا: أعد المحاولة بعد تأخير قصير. لا تكلّف شيئًا.

حلقة بسيطة تعيد المحاولة عند أخطاء الخادم وتتجاوز عند 404 تغطي معظم احتياجات الإنتاج.

كم تكلّف

يكلّف كل نص رصيدين. الطلبات التي لا تعيد نصًا أو تفشل من جانب sum.video لا تكلّف شيئًا، فلا يستنزف 404 رصيدك أبدًا. يمكنك معرفة رصيدك عبر GET /api/v1/credits.

تُباع الأرصدة في باقات لمرة واحدة لا تنتهي صلاحيتها أبدًا:

يحصل مشتركو Pro أيضًا على 100 رصيد إضافي كل شهر. للأحمال الأثقل، مثل استيعاب قناة كاملة، اقرأ السيناريو نصوص يوتيوب لتطبيق RAG على نطاق واسع الذي يتناول الشحن التلقائي والميزانيات. راجع أيضًا الأسعار.

حدود يجدر بك معرفتها قبل البناء

• لا تعمل إلا الفيديوهات التي لها ترجمات. وهذا السبب الرئيسي لـ 404 no_transcript.
• قد تحتوي الترجمات المُنشأة تلقائيًا على أخطاء، خصوصًا في الأسماء واللهجات والمصطلحات التقنية.
• تعيد الواجهة النص فقط، ولا تلخّص. إذا أردت ملخصات وطوابع زمنية ومحادثة فوق النص، فهذا ما يفعله ملخّص يوتيوب، وأداة النصوص هي النسخة التي لا تحتاج إلى برمجة لفيديو واحد.
• واجهة YouTube Data الرسمية ليست بديلًا هنا. طريقة تنزيل الترجمات فيها تتطلب صلاحية تعديل الفيديو، فهي مخصصة لفيديوهاتك أنت (وثائق Google).

المصادر

• YouTube Data API: Captions.download
• واجهة النصوص من sum.video