Captions

הערה: ב-13 במרץ 2024, הודענו על ידי YouTube שהמערכת מוציאה משימוש את הפרמטר sync של נקודות הקצה captions.insert ושל captions.update של נקודות הקצה של ה-API. הסנכרון האוטומטי של הכתוביות עדיין זמין ב-YouTube Studio. לפרטים נוספים אפשר לעיין בהיסטוריית הגרסאות של ה-API.

משאב caption מייצג רצועת כתוביות ב-YouTube. רצועת כתוביות משויכת לסרטון אחד בלבד ב-YouTube.

שיטות

ה-API תומך בשיטות הבאות למשאבים של captions:

list

אחזור רשימה של רצועות כתוביות שמשויכות לסרטון ספציפי. חשוב לשים לב שתגובת ה-API לא מכילה את הכתוביות עצמן, ושהשיטה captions.download מאפשרת לאחזר רצועת כתוביות. רוצים לנסות עכשיו?

הוספה

העלה רצועת כתוביות.

עדכון

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

מחיקה

מחיקת רצועת כתוביות שצוינה. כדאי לנסות עכשיו.

הורדה

הורדת רצועת כתוביות. רצועת הכתוביות מוחזרת בפורמט המקורי שלה, אלא אם הבקשה מציינת ערך לפרמטר tfmt ובשפה המקורית שלו, אלא אם הבקשה מציינת ערך לפרמטר tlang.

ייצוג משאבים

מבנה ה-JSON הבא מציג את הפורמט של משאב captions:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

תכונות

הטבלה הבאה מגדירה את המאפיינים שיופיעו במשאב הזה:

תכונות
kind	string מזהה את הסוג של משאב ה-API. הערך יהיה youtube#caption.
etag	etag ה-e של המשאב הזה.
id	string המזהה שמשמש את YouTube לזיהוי ייחודי של הטראק של הכתוביות.
snippet	object האובייקט snippet מכיל פרטים בסיסיים על הכיתוב.
snippet.videoId	string המזהה שמשמש את YouTube לזיהוי ייחודי של הסרטון המשויך לטראק של הכתוביות.
snippet.lastUpdated	datetime התאריך והשעה שבהם רצועת הכתוביות עודכנה לאחרונה. הערך מצוין בפורמט ISO 8601.
snippet.trackKind	string הסוג של טראק הכתוביות. הערכים החוקיים לנכס הזה הם: ASR – רצועת כתוביות שנוצרה באמצעות זיהוי דיבור אוטומטי. forced – טראק של כתוביות שמופעל כשלא נבחר אף טראק אחר בנגן. לדוגמה: בסרטון שבו מוצגים חייזרים שמדברים בשפה של חייזרים, רצועת הכתוביות מאולצת כך שתכלול כתוביות רק בשפה של חייזרים. standard – רצועת כתוביות רגילה. זהו ערך ברירת המחדל.
snippet.language	string השפה של רצועת הכתוביות. ערך המאפיין הוא תג שפה מסוג BCP-47.
snippet.name	string השם של רצועת הכתוביות. השם אמור להיות גלוי למשתמש כאפשרות במהלך ההפעלה. האורך המקסימלי הנתמך של השם הוא 150 תווים.
snippet.audioTrackType	string סוג הטראק של האודיו שמשויך לטראק של הכתוביות. הערכים החוקיים לנכס הזה הם: commentary – טראק הכתוביות תואם לטראק אחר של אודיו שכולל פרשנות, כמו פרשנות בספרייה. descriptive – רצועת הכתוביות תואמת לטראק חלופי של אודיו שכולל אודיו תיאורי נוסף. primary – רצועת הכתוביות תואמת לטראק הראשי של האודיו של הסרטון, שהיא טראק האודיו בדרך כלל שמשויך לסרטון. unknown – זהו ערך ברירת המחדל.
snippet.isCC	boolean מציין אם הטראק מכיל כתוביות לחירשים ולכבדי שמיעה. ערך ברירת המחדל הוא false.
snippet.isLarge	boolean מציין אם רצועת הכתוביות משתמשת בטקסט גדול עבור לקויי ראייה. ערך ברירת המחדל הוא false.
snippet.isEasyReader	boolean מציין אם רצועת הכתוביות מעוצבת כ"קורא קל", כלומר ברמת כיתה ג' של תלמידי שפה. ערך ברירת המחדל הוא false.
snippet.isDraft	boolean מציין אם רצועת הכתוביות היא טיוטה. אם הערך הוא true, הטראק לא גלוי לכולם. ערך ברירת המחדל הוא false.
snippet.isAutoSynced	boolean מציין אם המערכת של YouTube מסנכרנת את הטראק של כתוביות עם הטראק של האודיו בסרטון. הערך יהיה true אם התקבלה בקשה מפורשת לסנכרון כשרצועת הכתוביות הועלתה. לדוגמה, כשמפעילים את השיטה captions.insert או captions.update, אפשר להגדיר את הפרמטר sync כ-true כדי להורות ל-YouTube לסנכרן את הטראק שהועלה עם הסרטון. אם הערך הוא false, המערכת של YouTube משתמשת בקודי הזמן בטראק הכתוביות שהועלה כדי לקבוע מתי להציג כתוביות.
snippet.status	string הסטטוס של טראק הכתוביות. הערכים החוקיים לנכס הזה הם: failed serving syncing
snippet.failureReason	string הסיבה לכך שהמערכת של YouTube לא הצליחה לעבד את טראק הכתוביות. המאפיין הזה מוצג רק אם ערך הנכס ב-state הוא failed. הערכים החוקיים לנכס הזה הם: processingFailed – המערכת של YouTube לא הצליחה לעבד את רצועת הכתוביות שהעלית. unknownFormat – הפורמט של רצועת הכתוביות לא זוהה. unsupportedFormat – הפורמט של רצועת הכתוביות אינו נתמך.