Tous les champs de planification vidéo de l'API YouTube, et comment chacun échoue

Comment programmer une vidéo avec l'API YouTube ?

Il n'existe aucun endpoint de planification vidéo de l'API YouTube à appeler : la planification est une unique propriété datetime, status.publishAt, posée sur la ressource videos via videos.insert ou videos.update. La liste des méthodes n'a aucun verbe schedule, aucune ressource de planification distincte et aucun objet de file d'attente. Vous posez un horodatage, YouTube bascule la vidéo en public quand l'horloge l'atteint.

Cette conception explique pourquoi la plupart des bugs de planification sur YouTube sont des bugs de métadonnées. Tout ce qui peut mal tourner tourne mal dans la forme d'un seul champ ou dans la valeur de confidentialité posée à côté. La question du moment, quel créneau viser, est distincte et traitée dans quand publier une vidéo YouTube.

Qu'exige status.publishAt ?

La documentation de Google pour la ressource videos énonce la contrainte deux fois, en des termes différents, parce que les gens continuent de la manquer.

D'abord : « 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. »

Puis, une seconde fois, avec la partie qui casse les appels d'update : « 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. » Poser publishAt seul sur une vidéo déjà privée ne suffit pas. La requête doit porter private de nouveau.

Et une troisième condition : « This property can only be set if the video's privacy status is private and the video has never been published. » Une vidéo passée une fois en public ne peut pas être remise en planification en posant publishAt.

status.privacyStatus accepte trois valeurs : private, public et unlisted. Seule private est compatible avec une heure de publication programmée.

Quel format prend publishAt, et est-ce du RFC 3339 ?

Ici, la documentation et l'écosystème divergent sur le vocabulaire.

La ressource videos décrit status.publishAt comme un datetime et dit que « the value is specified in ISO 8601 format. » Elle ne dit RFC 3339 nulle part sur cette page. La chaîne RFC 3339 apparaît bien dans la référence de la YouTube Data API, mais sur d'autres champs : search.list documente publishedAfter et publishedBefore comme « an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z). »

En pratique, les deux étiquettes décrivent la même chaîne acceptée pour ce champ, parce que RFC 3339 est un profil d'ISO 8601 et que le scalaire datetime de Google est du RFC 3339 sur l'ensemble de ses API. Ce qui compte, c'est la forme que vous envoyez :

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

Une date sans heure, une heure sans décalage, ou un horodatage local dont le fuseau est sous-entendu plutôt qu'énoncé, voilà d'où vient invalidPublishAt. Envoyez un décalage explicite ou un Z. Si vous convertissez depuis l'heure locale d'un utilisateur, faites la conversion avant la requête plutôt que d'espérer que l'API déduise un fuseau qu'on ne lui a jamais donné.

Que se passe-t-il si l'horodatage est dans le passé ?

La vidéo est publiée. Immédiatement. C'est documenté et ce n'est pas une erreur.

« 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. »

Ce comportement mérite un garde-fou dans tout chemin de code qui calcule une heure de publication. Une conversion de fuseau qui atterrit une heure en retard, une file qui relance une tâche périmée, ou un brouillon resté dans une étape de relecture tout un week-end n'échoueront pas bruyamment. Ils passeront en ligne. Vérifiez que l'horodatage calculé est dans le futur avant de l'envoyer, parce que YouTube ne le fera pas pour vous.

Quelles erreurs l'API renvoie-t-elle ?

videos.insert et videos.update documentent tous deux la même erreur de planification, plus un ensemble de voisines qui se déclenchent pour les métadonnées envoyées à côté.

videos.insert en ajoute trois qui lui sont propres : mediaBodyRequired quand la requête ne porte aucun contenu vidéo, invalidFilename quand l'en-tête Slug est malformé, et uploadLimitExceeded, que la documentation glose par « the user has exceeded the number of videos they may upload. »

Notez que forbiddenPrivacySetting est un 403, pas un 400. Si vous n'attrapez que les 400 autour d'un appel de planification, une valeur de confidentialité rejetée échappera au gestionnaire.

Que fait part sur un update, et pourquoi cela supprime-t-il des choses ?

C'est la deuxième erreur la plus coûteuse après celle de l'horodatage passé, et elle découle directement de la façon dont videos.update traite le paramètre part. C'est aussi pourquoi la plupart des équipes passent par un planificateur de vidéos YouTube plutôt que d'appeler l'endpoint elles-mêmes.

La documentation est explicite : « this method will override the existing values for all of the mutable properties that are contained in any parts that the parameter value specifies. » Elle donne ensuite le cas exact qui mord les planificateurs : « 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 n'est donc pas un patch. Chaque propriété modifiable de status que vous omettez est effacée. La même chose vaut pour part=snippet, et c'est pourquoi une mise à jour de planification qui n'envoie que publishAt sous part=snippet,status peut effacer une description, aussi près de la limite de caractères de la description que vous l'ayez écrite. Lisez la ressource actuelle, modifiez les champs que vous voulez changer, et renvoyez la partie entière.

Que coûte la planification en quota ?

Les deux appels se trouvent dans des pools différents depuis le changement de compartiments de juin 2026.

Cette asymétrie a une conséquence de planification. Poser publishAt dans le videos.insert d'origine ne coûte rien de plus ; c'est l'envoi lui-même qui puise dans le compartiment de 100 envois par jour. Reprogrammer ensuite coûte 50 unités par tentative sur le pool principal de 10 000 unités, et chaque miniature posée aussi. Un flux qui envoie en privé, met à jour la planification deux fois, puis pose une miniature, a dépensé 150 unités sur une vidéo avant que personne ne l'ait regardée. Si cette arithmétique commence à serrer, la sortie passe par une extension de quota et l'audit derrière, pas par davantage de tentatives.

Questions fréquentes

Quel champ programme une vidéo YouTube via l'API ?

status.publishAt sur la ressource videos. C'est un datetime que vous posez via videos.insert au moment de l'envoi ou via videos.update ensuite. Il n'existe aucune méthode ni ressource de planification dédiée dans la YouTube Data API.

Pourquoi ma mise à jour de publishAt est-elle rejetée ?

La cause la plus courante est la confidentialité. La documentation de Google dit que lorsque vous posez publishAt via videos.update, « you must also set the status.privacyStatus property value to private even if the video is already private. » Envoyer publishAt sans privacyStatus dans la même requête ne programmera pas la vidéo.

Puis-je programmer une vidéo déjà publique ?

Non. La documentation énonce que publishAt « can only be set if the video's privacy status is private and the video has never been published. » Une fois qu'une vidéo est passée en public, ce champ lui est fermé définitivement.

Quel format d'heure publishAt accepte-t-il ?

La page de la ressource videos de Google décrit la valeur comme de l'ISO 8601. Envoyez une date et une heure complètes avec un décalage UTC explicite ou un Z final, comme 2026-10-01T14:30:00Z. Les valeurs sans heure ou sans décalage de fuseau sont la source habituelle d'invalidPublishAt.

Que se passe-t-il si publishAt est dans le passé ?

La vidéo est publiée immédiatement. Google documente cela comme l'équivalent d'un passage de privacyStatus de private à public. Aucune erreur n'est renvoyée, validez donc l'horodatage avant de l'envoyer.

Combien de quota la planification consomme-t-elle ?

videos.insert coûte 1 unité sur un compartiment Video Uploads plafonné à 100 appels par jour. videos.update coûte 50 unités sur le pool journalier principal. Poser publishAt pendant l'insert initial ne coûte donc rien au-delà de l'envoi ; chaque reprogrammation ultérieure coûte 50.

Puis-je programmer une vidéo avec privacyStatus sur unlisted ?

status.privacyStatus accepte trois valeurs, private, public et unlisted, mais seul private permet une heure de publication programmée. Définir publishAt pendant que privacyStatus vaut unlisted ou public ne programme rien. Envoie privacyStatus à private dans la même requête que celle qui porte publishAt.

Pourquoi la description de ma vidéo a-t-elle disparu après la mise à jour de la programmation ?

videos.update écrase chaque propriété modifiable des parties indiquées, pas seulement les champs présents dans le corps de la requête. Un appel avec part=snippet,status qui n'envoie que publishAt efface tout champ de snippet omis, description comprise. Lis la ressource actuelle, garde les champs à préserver, et renvoie la partie entière avec ton changement de publishAt.

forbiddenPrivacySetting est-il une erreur 400 ou 403 ?

C'est une 403, classée sous forbidden plutôt que badRequest. Un gestionnaire qui ne surveille que les 400 autour d'un appel de programmation laisse passer un paramètre de confidentialité rejeté sans le voir. Surveille les 403 en plus des 400 en validant une réponse de videos.insert ou videos.update.

Combien de nouvelles vidéos puis-je programmer par jour via l'API ?

Jusqu'à 100. videos.insert puise dans un bucket Video Uploads plafonné à 100 appels par jour, et chaque appel coûte 1 unité de ce plafond quotidien, séparé du pool principal de 10 000 unités. Reprogrammer une vidéo déjà mise en ligne passe par videos.update, qui coûte 50 unités du pool principal sans toucher au plafond d'upload.