איך לקבל תמלול של יוטיוב באמצעות API (curl, Python, JavaScript)

כדי לקבל תמלול של יוטיוב באמצעות API, שלח בקשת HTTP אחת עם כתובת ה-URL או המזהה של הסרטון ומפתח API, וקרא את התמלול מהתשובה. המדריך הזה מראה את הבקשה ב-curl, ב-Python וב-JavaScript באמצעות ה-API של התמלולים של sum.video, ואחר כך עובר על פורמטים, שגיאות ועלויות.

מה ה-API מחזיר

נקודת הקצה מחזירה את הכתוביות הקיימות של סרטון ציבורי ביוטיוב, בין שנכתבו על ידי היוצר ובין שנוצרו אוטומטית על ידי יוטיוב. היא לא מתמללת אודיו. אם לסרטון אין כתוביות, תקבל שגיאה במקום ניחוש (עוד על כך בהמשך).

היסודות:

• נקודת קצה: POST https://sum.video/api/v1/transcript (גם GET עובד)
• אימות: המפתח שלך בכותרת X-API-Key, או Authorization: Bearer <key>
• קלט: url או video_id
• lang אופציונלי (ברירת מחדל en)
• format אופציונלי: json, text או srt

התשובה גם מציינת את השפה האמיתית של רצועת הכתוביות ואם היא נוצרה אוטומטית, כך שתדע מה האיכות שכדאי לצפות לה.

שלב 1: צור מפתח API

התחבר וצור מפתח בלוח הבקרה של ה-API (/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 גם עובד, אפשר לבדוק מתוך סקריפט שרק בונה כתובות URL. עדיף להעביר את המפתח בכותרת, כדי שלא יגיע ליומנים.

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. התשובה מדווחת על השפה של הרצועה שהוחזרה בפועל, לכן בדוק אותה במקום להניח. לסרטון יש לרוב רק רצועת כתוביות אחת, וה-API מחזיר כתוביות אמיתיות, ולכן הוא לא מתרגם בשבילך.

שלב 5: טפל בשגיאות

תכנן את המקרים האלה מהיום הראשון:

• 404 no_transcript: לסרטון אין כתוביות, או שהוא שידור חי, סרטון פרטי או סרטון שהוסר. אין מה לנסות שוב. דלג עליו, או בקש מהמשתמש סרטון אחר.
• 402 budget_exceeded: הגעת למגבלת הקרדיטים החודשית שהגדרת. ראה את הסעיף הבא.
• מגבלת קצב: כל מפתח מאפשר 60 בקשות בדקה. פזר משימות אצווה, והאט כשמגבילים אותך.
• כשלים מצידנו: נסה שוב אחרי השהיה קצרה. הם לא עולים כלום.

לולאה פשוטה שמנסה שוב בשגיאות שרת ומדלגת ב-404 מכסה את רוב צורכי הייצור.

כמה זה עולה

כל תמלול עולה 2 קרדיטים. בקשות שלא מחזירות תמלול, או שנכשלות מצד sum.video, לא עולות כלום, כך ש-404 אף פעם לא מרוקן את היתרה שלך. את היתרה אפשר לראות עם GET /api/v1/credits.

הקרדיטים נמכרים בחבילות חד-פעמיות שלעולם לא פוקעות:

מנויי Pro מקבלים גם 100 קרדיטי בונוס בכל חודש. לעומסים כבדים יותר, כמו טעינת ערוץ שלם, קרא את התרחיש תמלולי יוטיוב לאפליקציית RAG בקנה מידה גדול, שעוסק בטעינה אוטומטית ובתקציבים. ראה גם את המחירים.

מגבלות שכדאי להכיר לפני שבונים

• רק סרטונים עם כתוביות עובדים. זו הסיבה העיקרית ל-404 no_transcript.
• כתוביות שנוצרו אוטומטית עשויות להכיל טעויות, במיוחד בשמות, במבטא ובמונחים טכניים.
• ה-API מחזיר רק את התמלול. הוא לא מסכם. אם אתה רוצה סיכומים, חותמות זמן ושיחה מעל תמלול, מסכם היוטיוב עושה זאת, וכלי התמלול הוא הגרסה ללא קוד לסרטון אחד.
• ה-API הרשמי YouTube Data אינו תחליף כאן. שיטת הורדת הכתוביות שלו דורשת הרשאה לערוך את הסרטון, ולכן היא מיועדת לסרטונים שלך (תיעוד של גוגל).

מקורות

• YouTube Data API: Captions.download
• ה-API של התמלולים של sum.video