Jedes Feld, mit dem die YouTube API ein Video plant, und wie es scheitert

Wie planst du ein Video mit der YouTube API?

Es gibt keinen Endpunkt, um ein Video per YouTube API zu planen: Die Planung ist eine einzelne Datums-Eigenschaft, status.publishAt, gesetzt an der videos-Ressource über entweder videos.insert oder videos.update. Die Methodenliste hat kein schedule-Verb, keine separate Planungsressource und kein Warteschlangenobjekt. Du setzt einen Zeitstempel, YouTube stellt das Video auf öffentlich, sobald die Uhr ihn erreicht.

Wegen dieses Entwurfs sind die meisten Planungsfehler auf YouTube Metadatenfehler. Alles, was schiefgehen kann, geht in der Form eines Feldes oder in dem Datenschutzwert daneben schief. Die Zeitfrage, auf welchen Slot du zielst, ist getrennt und wird in wann man ein YouTube-Video hochlädt behandelt.

Was verlangt status.publishAt?

Googles Dokumentation zur videos-Ressource nennt die Bedingung zweimal, mit unterschiedlichen Worten, weil sie ständig überlesen wird.

Zuerst: „The date and time when the video is scheduled to publish. It can be set only if the privacy status of the video is private.“

Dann ein zweites Mal, mit dem Teil, der Update-Aufrufe zerlegt: „If you set this property's value when calling the videos.update method, you must also set the status.privacyStatus property value to private even if the video is already private.“ publishAt allein an einem bereits privaten Video zu setzen reicht nicht. Die Anfrage muss private erneut mitführen.

Und eine dritte Bedingung: „This property can only be set if the video's privacy status is private and the video has never been published.“ Ein Video, das einmal öffentlich war, lässt sich durch Setzen von publishAt nicht wieder in eine Planung bringen.

status.privacyStatus nimmt drei Werte an: private, public und unlisted. Nur private verträgt sich mit einer geplanten Veröffentlichungszeit.

Welches Format nimmt publishAt an, und ist es RFC 3339?

Hier sind sich Dokumentation und Ökosystem über das Vokabular uneinig.

Die videos-Ressource beschreibt status.publishAt als datetime und sagt, „the value is specified in ISO 8601 format“. Von RFC 3339 steht auf dieser Seite nirgends etwas. Die Zeichenfolge RFC 3339 taucht in der Referenz der YouTube Data API durchaus auf, aber an anderen Feldern: search.list dokumentiert publishedAfter und publishedBefore als „an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z)“.

In der Praxis beschreiben die beiden Etiketten für dieses Feld dieselbe akzeptierte Zeichenfolge, weil RFC 3339 ein Profil von ISO 8601 ist und Googles datetime-Skalar über seine APIs hinweg RFC 3339 ist. Worauf es ankommt, ist die Form, die du sendest:

2026-10-01T14:30:00Z
2026-10-01T10:30:00-04:00

Ein Datum ohne Zeit, eine Zeit ohne Offset oder ein lokaler Zeitstempel mit implizierter statt genannter Zone ist die Quelle von invalidPublishAt. Sende einen expliziten Offset oder ein Z. Wenn du aus der Ortszeit eines Nutzers umrechnest, tu das vor der Anfrage, statt zu hoffen, die API errate eine Zone, die sie nie bekommen hat.

Was passiert, wenn der Zeitstempel in der Vergangenheit liegt?

Es wird veröffentlicht. Sofort. Das ist dokumentiert und es ist kein Fehler.

„If your request schedules a video to be published at some time in the past, the video will be published right away. As such, the effect of setting the status.publishAt property to a past date and time is the same as of changing the video's privacyStatus from private to public.“

Dieses Verhalten verdient in jedem Codepfad, der eine Veröffentlichungszeit berechnet, eine Absicherung. Eine Zeitzonenumrechnung, die eine Stunde danebenliegt, eine Warteschlange, die einen veralteten Job erneut versucht, oder ein Entwurf, der über ein Wochenende in einem Freigabeschritt lag, scheitert nicht laut. Es geht live. Prüfe, dass der berechnete Zeitstempel in der Zukunft liegt, bevor du ihn sendest, denn YouTube tut das nicht für dich.

Welche Fehler liefert die API?

Sowohl videos.insert als auch videos.update dokumentieren denselben Planungsfehler, plus eine Reihe von Nachbarn, die für die mitgesendeten Metadaten auslösen.

videos.insert ergänzt drei eigene: mediaBodyRequired, wenn die Anfrage keinen Videoinhalt trägt, invalidFilename, wenn der Slug-Header fehlerhaft ist, und uploadLimitExceeded, das die Doku als „the user has exceeded the number of videos they may upload“ umschreibt.

Beachte, dass forbiddenPrivacySetting ein 403 ist und kein 400. Wenn du rund um einen Planungsaufruf nur 400er abfängst, entkommt ein abgelehnter Datenschutzwert deinem Handler.

Was macht part bei einem Update, und warum löscht es Dinge?

Das ist nach dem Zeitstempel in der Vergangenheit der zweitteuerste Fehler, und er folgt direkt daraus, wie videos.update den Parameter part behandelt. Genau deshalb greifen die meisten Teams zu einem YouTube-Video-Scheduler, statt den Endpunkt selbst aufzurufen.

Die Dokumentation ist eindeutig: „this method will override the existing values for all of the mutable properties that are contained in any parts that the parameter value specifies.“ Sie nennt dann genau den Fall, der Planer beißt: „if your request is updating a private video, and the request's part parameter value includes the status part, the video's privacy setting will be updated to whatever value the request body specifies. If the request body does not specify a value, the existing privacy setting will be removed and the video will revert to the default privacy setting.“

part=status ist also kein Patch. Jede veränderbare Eigenschaft innerhalb von status, die du weglässt, wird geleert. Dasselbe gilt für part=snippet, weshalb ein Planungs-Update, das unter part=snippet,status nur publishAt sendet, eine Beschreibung löschen kann, egal wie nah an dem Zeichenlimit der Beschreibung du sie geschrieben hattest. Lies die aktuelle Ressource, ändere die Felder, die du ändern willst, und sende den ganzen Part zurück.

Was kostet Planung an Quote?

Die beiden Aufrufe sitzen seit der Eimer-Änderung vom Juni 2026 in unterschiedlichen Töpfen.

Die Asymmetrie hat eine Planungsfolge. publishAt gleich im ursprünglichen videos.insert zu setzen kostet nichts extra; der Upload selbst zieht am Eimer mit 100 pro Tag. Späteres Umplanen kostet 50 Einheiten pro Versuch aus dem Haupttopf von 10.000 Einheiten, und jedes gesetzte Vorschaubild ebenso. Ein Ablauf, der privat hochlädt, dann zweimal die Planung ändert und dann ein Vorschaubild setzt, hat für ein Video 150 Einheiten ausgegeben, bevor es jemand gesehen hat. Wenn diese Rechnung eng wird, führt der Weg hinaus über eine Quotenerhöhung und das Audit dahinter, nicht über mehr Wiederholungen.

Häufig gestellte Fragen

Welches Feld plant ein YouTube-Video über die API?

status.publishAt an der videos-Ressource. Es ist ein datetime, das du beim Upload über videos.insert oder danach über videos.update setzt. Es gibt in der YouTube Data API keine eigene Planungsmethode und keine eigene Planungsressource.

Warum wird mein publishAt-Update abgelehnt?

Die häufigste Ursache ist der Datenschutzwert. Googles Dokumentation sagt, dass du beim Setzen von publishAt über videos.update „must also set the status.privacyStatus property value to private even if the video is already private“. publishAt ohne privacyStatus in derselben Anfrage zu senden plant das Video nicht.

Kann ich ein Video planen, das bereits öffentlich ist?

Nein. Die Dokumentation hält fest, dass publishAt „can only be set if the video's privacy status is private and the video has never been published“. Sobald ein Video öffentlich war, ist dieses Feld für es dauerhaft geschlossen.

Welches Zeitformat nimmt publishAt an?

Googles Seite zur videos-Ressource beschreibt den Wert als ISO 8601. Sende ein vollständiges Datum mit Zeit und explizitem UTC-Offset oder abschließendem Z, etwa 2026-10-01T14:30:00Z. Werte ohne Zeit oder ohne Zonen-Offset sind die übliche Quelle von invalidPublishAt.

Was passiert, wenn publishAt in der Vergangenheit liegt?

Das Video wird sofort veröffentlicht. Google dokumentiert das als gleichwertig mit dem Wechsel von privacyStatus von privat auf öffentlich. Es kommt kein Fehler zurück, prüfe den Zeitstempel also vor dem Senden.

Wie viel Quote verbraucht die Planung?

videos.insert kostet 1 Einheit aus einem Video-Uploads-Eimer, der bei 100 Aufrufen pro Tag gedeckelt ist. videos.update kostet 50 Einheiten aus dem täglichen Haupttopf. publishAt beim ersten Insert zu setzen kostet also nichts über den Upload hinaus; jede spätere Umplanung kostet 50.

Kann ich ein Video planen, wenn privacyStatus auf unlisted steht?

status.privacyStatus akzeptiert drei Werte, private, public und unlisted, aber nur private lässt eine geplante Veröffentlichungszeit zu. Wird publishAt gesetzt, während privacyStatus unlisted oder public ist, wird das Video nicht geplant. Schicke privacyStatus als private in derselben Anfrage, die publishAt enthält.

Warum ist die Beschreibung meines Videos nach dem Update des Zeitplans verschwunden?

videos.update überschreibt jede veränderbare Eigenschaft innerhalb der angegebenen part-Werte, nicht nur die Felder aus dem Anfragekörper. Ein Aufruf mit part=snippet,status, der nur publishAt sendet, löscht jedes ausgelassene snippet-Feld, einschließlich der Beschreibung. Lies die aktuelle Ressource, behalte die Felder, die erhalten bleiben sollen, und schicke den gesamten part zusammen mit der publishAt-Änderung zurück.

Ist forbiddenPrivacySetting ein 400er- oder ein 403er-Fehler?

Es ist ein 403er, eingeordnet unter forbidden statt badRequest. Eine Fehlerbehandlung, die bei einem Scheduling-Aufruf nur auf 400 prüft, lässt eine abgelehnte Datenschutzeinstellung unbemerkt durch. Prüfe bei videos.insert und videos.update sowohl auf 403 als auch auf 400.

Wie viele neue Videos kann ich pro Tag über die API planen?

Bis zu 100. videos.insert schöpft aus einem Video Uploads Bucket, der auf 100 Aufrufe pro Tag begrenzt ist, und jeder Aufruf kostet 1 Einheit aus diesem Tageslimit, getrennt vom 10.000-Einheiten-Hauptpool. Eine spätere Umplanung läuft über videos.update, das 50 Einheiten aus dem Hauptpool kostet und das Upload-Limit nicht anrührt.