דף זה תורגם על ידי Cloud Translation API.

Captions

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

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

שיטות

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

list: אחזור רשימה של רצועות כתוביות שמשויכות לסרטון מסוים. חשוב לזכור שתגובת ה-API לא מכילה את הכתוביות בפועל, ושהשימוש ב-method‏ 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` ה-Etag של משאב זה.
`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` – הפורמט של רצועת הכתוביות לא נתמך.