Todo campo para agendar vídeo pela API do YouTube e como cada um falha

Como agendar um vídeo com a API do YouTube?

Não existe endpoint para chamar e agendar vídeo pela API do YouTube: o agendamento é uma única propriedade de data e hora, status.publishAt, definida no recurso videos por videos.insert ou videos.update. A lista de métodos não tem verbo schedule, nem recurso de agendamento separado, nem objeto de fila. Você define um carimbo de tempo, o YouTube torna o vídeo público quando o relógio chega lá.

Esse desenho é a razão de a maioria dos bugs de agendamento no YouTube serem bugs de metadados. Tudo que pode dar errado dá errado no formato de um campo ou no valor de privacidade ao lado dele. A questão de horário, qual janela mirar, é separada e está coberta em quando publicar um vídeo no YouTube.

O que o status.publishAt exige?

A documentação do Google para o recurso videos afirma a restrição duas vezes, com palavras diferentes, porque as pessoas continuam deixando passar.

Primeiro: "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."

Depois, uma segunda vez, com a parte que quebra as chamadas de 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." Definir só o publishAt em um vídeo já privado não basta. A requisição precisa carregar private de novo.

E uma terceira condição: "This property can only be set if the video's privacy status is private and the video has never been published." Um vídeo que ficou público uma vez não pode voltar a ser agendado definindo publishAt.

O status.privacyStatus aceita três valores: private, public e unlisted. Só private é compatível com um horário de publicação agendado.

Que formato o publishAt aceita, e é RFC 3339?

Aqui a documentação e o ecossistema discordam sobre vocabulário.

O recurso videos descreve status.publishAt como um datetime e diz que "the value is specified in ISO 8601 format." Ele não fala em RFC 3339 em lugar nenhum dessa página. A string RFC 3339 aparece sim na referência da YouTube Data API, mas em outros campos: search.list documenta publishedAfter e publishedBefore como "an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z)."

Na prática os dois rótulos descrevem a mesma string aceita nesse campo, porque RFC 3339 é um perfil de ISO 8601 e o escalar datetime do Google é RFC 3339 em todas as APIs dele. O que importa é o formato que você envia:

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

Uma data sem hora, uma hora sem deslocamento, ou um carimbo local com o fuso implícito em vez de declarado é de onde vem o invalidPublishAt. Envie um deslocamento explícito ou um Z. Se você converte a partir do horário local de um usuário, faça a conversão antes da requisição em vez de torcer para a API deduzir um fuso que nunca recebeu.

O que acontece se o carimbo de tempo estiver no passado?

Ele publica. Na hora. Isso é documentado e não é erro.

"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."

Esse comportamento merece uma proteção em qualquer trecho de código que calcula um horário de publicação. Uma conversão de fuso que cai uma hora atrás, uma fila que repete um job velho, ou um rascunho que ficou parado em uma etapa de revisão durante o fim de semana não vai falhar em voz alta. Vai ao ar. Valide que o carimbo calculado está no futuro antes de enviar, porque o YouTube não faz isso por você.

Que erros a API devolve?

Tanto videos.insert quanto videos.update documentam o mesmo erro de agendamento, mais um conjunto de vizinhos que disparam pelos metadados enviados junto.

O videos.insert acrescenta três próprios: mediaBodyRequired quando a requisição não carrega conteúdo de vídeo, invalidFilename quando o cabeçalho Slug está malformado, e uploadLimitExceeded, que a documentação explica como "the user has exceeded the number of videos they may upload."

Repare que forbiddenPrivacySetting é um 403, não um 400. Se você só captura 400 em torno de uma chamada de agendamento, um valor de privacidade rejeitado escapa do tratador.

O que o part faz em um update, e por que ele apaga coisas?

Esse é o segundo erro mais caro depois do carimbo no passado, e é consequência direta de como o videos.update trata o parâmetro part. É também por isso que a maioria dos times recorre a um agendador de vídeos do YouTube em vez de chamar o endpoint por conta própria.

A documentação é explícita: "this method will override the existing values for all of the mutable properties that are contained in any parts that the parameter value specifies." Em seguida ela dá o caso exato que morde quem agenda: "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."

Ou seja, part=status não é um patch. Toda propriedade mutável dentro de status que você omite é zerada. O mesmo vale para part=snippet, e é por isso que uma atualização de agendamento que envia só publishAt sob part=snippet,status consegue apagar uma descrição, por mais perto que você tivesse escrito do limite de caracteres da descrição. Leia o recurso atual, altere os campos que você quer mudar e devolva a parte inteira.

Quanto o agendamento custa de cota?

As duas chamadas ficam em potes diferentes desde a mudança de baldes de junho de 2026.

A assimetria tem consequência de planejamento. Definir publishAt no videos.insert original não custa nada a mais; o upload em si é o que consome o balde de 100 por dia. Reagendar depois custa 50 unidades por tentativa do pote principal de 10.000 unidades, e cada miniatura que você define custa o mesmo. Um fluxo que sobe em modo privado, depois atualiza o agendamento duas vezes, depois define uma miniatura, gastou 150 unidades em um vídeo antes de alguém assistir. Se essa aritmética começa a apertar, a saída é uma extensão de cota e a auditoria por trás dela, não mais tentativas.

Perguntas frequentes

Que campo agenda um vídeo do YouTube pela API?

status.publishAt no recurso videos. É um datetime que você define por videos.insert no momento do upload ou por videos.update depois. Não existe método nem recurso dedicado a agendamento na YouTube Data API.

Por que minha atualização de publishAt é rejeitada?

A causa mais comum é privacidade. A documentação do Google diz que, ao definir publishAt por videos.update, "you must also set the status.privacyStatus property value to private even if the video is already private." Enviar publishAt sem privacyStatus na mesma requisição não agenda o vídeo.

Dá para agendar um vídeo que já está público?

Não. A documentação afirma que publishAt "can only be set if the video's privacy status is private and the video has never been published." Depois que um vídeo ficou público, esse campo fica fechado para ele em definitivo.

Que formato de horário o publishAt aceita?

A página do recurso videos do Google descreve o valor como ISO 8601. Envie data e hora completas com deslocamento UTC explícito ou um Z no fim, como 2026-10-01T14:30:00Z. Valores sem hora ou sem deslocamento de fuso são a fonte habitual de invalidPublishAt.

O que acontece se o publishAt estiver no passado?

O vídeo publica na hora. O Google documenta isso como equivalente a trocar o privacyStatus de privado para público. Nenhum erro é devolvido, então valide o carimbo antes de enviar.

Quanta cota o agendamento consome?

videos.insert custa 1 unidade de um balde de Video Uploads com teto de 100 chamadas por dia. videos.update custa 50 unidades do pote diário principal. Definir publishAt no insert inicial portanto não custa nada além do upload; todo reagendamento posterior custa 50.

Dá para agendar um vídeo com privacyStatus em unlisted?

status.privacyStatus aceita três valores, private, public e unlisted, mas só private aceita um horário de publicação agendado. Definir publishAt enquanto privacyStatus está em unlisted ou public não agenda o vídeo. Envie privacyStatus como private na mesma requisição que carrega o publishAt.

Por que a descrição do meu vídeo sumiu depois que atualizei o agendamento?

O videos.update sobrescreve toda propriedade mutável dentro das partes informadas, não só os campos enviados no corpo da requisição. Uma chamada com part=snippet,status que manda só o publishAt apaga qualquer campo do snippet que ficou de fora, incluindo a descrição. Leia o recurso atual, mantenha os campos que quer preservar e devolva a parte inteira junto com a mudança de publishAt.

forbiddenPrivacySetting é um erro 400 ou 403?

É um 403, classificado como forbidden e não como badRequest. Um tratamento que só verifica erros 400 numa chamada de agendamento deixa passar despercebido um ajuste de privacidade rejeitado. Verifique tanto 403 quanto 400 ao validar uma resposta do videos.insert ou do videos.update.

Quantos vídeos novos dá para agendar pela API por dia?

Até 100. O videos.insert consome de um bucket de Video Uploads limitado a 100 chamadas por dia, e cada chamada custa 1 unidade desse limite diário, separado do pool principal de 10.000 unidades. Reagendar um vídeo já enviado passa pelo videos.update, que custa 50 unidades do pool principal sem tocar no limite de upload.