Captions

Hinweis: Am 13. März 2024 gab YouTube bekannt, dass der sync-Parameter für die API-Endpunkte captions.insert und captions.update eingestellt wird. Die automatische Synchronisierung von Untertiteln ist in YouTube Creator Studio weiterhin verfügbar. Weitere Informationen finden Sie unter API-Überarbeitungsverlauf.

Eine caption-Ressource steht für einen YouTube-Untertiteltrack. Ein Untertiteltrack ist mit genau einem YouTube-Video verknüpft.

Methoden

Die API unterstützt die folgenden Methoden für captions-Ressourcen:

list

Ruft eine Liste der Untertitel-Tracks ab, die mit einem bestimmten Video verknüpft sind. Beachte, dass die API-Antwort nicht die tatsächlichen Untertitel enthält und dass die captions.download-Methode die Möglichkeit bietet, einen Untertiteltrack abzurufen. Jetzt ausprobieren

insert

Laden Sie einen Untertiteltrack hoch.

Update

Untertitel aktualisieren Beim Aktualisieren eines Untertiteltracks kannst du den Status des Entwurfs ändern, eine neue Untertiteldatei für den Track hochladen oder beides.

delete

Einen bestimmten Untertiteltrack löschen. Hier kannst du die Funktion ausprobieren.

Herunterladen

Untertitel herunterladen Der Untertiteltrack wird im ursprünglichen Format zurückgegeben, sofern in der Anfrage kein Wert für den Parameter tfmt und in der Originalsprache angegeben ist, sofern in der Anfrage kein Wert für den Parameter tlang angegeben ist.

Ressourcendarstellung

Die folgende JSON-Struktur zeigt das Format einer captions-Ressource:

{
  "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
  }
}

Attribute

In der folgenden Tabelle werden die Attribute definiert, die in dieser Ressource angezeigt werden:

Attribute
kind	string Identifiziert den Typ der API-Ressource. Der Wert ist youtube#caption.
etag	etag Das ETag dieser Ressource.
id	string Die ID, mit der YouTube den Untertiteltrack eindeutig identifiziert.
snippet	object Das snippet-Objekt enthält grundlegende Details zum Untertitel.
snippet.videoId	string Die ID, die YouTube verwendet, um das mit dem Untertiteltrack verknüpfte Video eindeutig zu identifizieren.
snippet.lastUpdated	datetime Datum und Uhrzeit der letzten Aktualisierung des Untertiteltracks. Der Wert wird im ISO 8601-Format angegeben.
snippet.trackKind	string Der Typ des Untertitel-Tracks. Gültige Werte für dieses Attribut sind: ASR: Ein Untertiteltrack, der durch automatische Spracherkennung generiert wird. forced: Ein Untertiteltrack, der abgespielt wird, wenn kein anderer Track im Player ausgewählt ist. Beispielsweise kann es sein, dass in einem Video, das Aliens zeigt, die in einer fremdsprachigen Sprache sprechen, eine erzwungene Untertitelspur vorhanden ist, um nur Untertitel für diese Sprache anzuzeigen. standard: Ein normaler Untertiteltrack. „Immer“ ist der Standardwert.
snippet.language	string Die Sprache des Untertiteltracks. Der Attributwert ist das Sprachtag BCP-47.
snippet.name	string Der Name des Untertiteltracks. Der Name soll dem Nutzer während der Wiedergabe als Option angezeigt werden. Die maximale Länge des Namens beträgt 150 Zeichen.
snippet.audioTrackType	string Der Typ des Audiotracks, der dem Untertiteltrack zugeordnet ist. Gültige Werte für diese Eigenschaft sind: commentary: Der Untertiteltrack entspricht einem alternativen Audiotrack, der Kommentare enthält, z. B. Verzeichniskommentare. descriptive: Der Untertiteltrack entspricht einem alternativen Audiotrack, der zusätzliche beschreibende Audioinhalte enthält. primary: Der Untertiteltrack entspricht dem primären Audiotrack des Videos, also dem Audiotrack, der normalerweise dem Video zugeordnet ist. unknown: Das ist der Standardwert.
snippet.isCC	boolean Gibt an, ob der Titel Untertitel für gehörlose und schwerhörige Nutzer enthält. Der Standardwert ist false.
snippet.isLarge	boolean Gibt an, ob im Untertiteltrack großer Text für Sehbehinderte verwendet wird. Der Standardwert ist false.
snippet.isEasyReader	boolean Gibt an, ob Untertiteltracks für „Easy Reader“ formatiert sind, d. h. für Sprachlerner einer dritten Klasse. Der Standardwert ist false.
snippet.isDraft	boolean Gibt an, ob es sich bei dem Untertiteltrack um einen Entwurf handelt. Lautet der Wert true, ist der Track nicht öffentlich sichtbar. Der Standardwert ist false.
snippet.isAutoSynced	boolean Gibt an, ob YouTube den Untertiteltrack mit dem Audiotrack im Video synchronisiert hat. Der Wert ist true, wenn beim Hochladen des Untertiteltracks explizit eine Synchronisierung angefordert wurde. Wenn du beispielsweise die Methoden captions.insert oder captions.update aufrufst, kannst du den sync-Parameter auf true setzen, um YouTube anzuweisen, den hochgeladenen Track mit dem Video zu synchronisieren. Wenn der Wert false ist, ermittelt YouTube anhand der Timecodes im hochgeladenen Untertiteltrack, wann Untertitel eingeblendet werden.
snippet.status	string Der Status des Untertitel-Tracks. Gültige Werte für dieses Attribut sind: failed serving syncing
snippet.failureReason	string Der Grund, warum YouTube den Untertiteltrack nicht verarbeiten konnte. Dieses Attribut ist nur vorhanden, wenn der Wert des Attributs state failed ist. Gültige Werte für dieses Attribut sind: processingFailed: YouTube konnte den hochgeladenen Untertiteltrack nicht verarbeiten. unknownFormat: Das Format des Untertiteltracks wurde nicht erkannt. unsupportedFormat: Das Format des Untertiteltracks wird nicht unterstützt.