Exportar arquivos para o YouTube pela linha de comando
Você pode fazer upload de um vídeo concluído pelo terminal usando as bibliotecas Python de código aberto do Google. A CLI abaixo seleciona um arquivo local e um JSON de metadados, solicita que você autorize um canal e retorna o ID do vídeo após o YouTube aceitar o upload. Ela mantém os vídeos privados e desativa as notificações aos inscritos.
Limitações importantes da API do YouTube
Este exemplo se destina a um upload com acompanhamento no Linux, com Bash e um navegador na mesma máquina. Ele aceita um MP4 local não vazio de até 64 MiB, com nome de arquivo em UTF-8. O arquivo já precisa estar concluído e ser reproduzível; o script não valida nem transcodifica seu conteúdo. Há um prazo total de cinco minutos, incluindo autorização e transferência, portanto até um arquivo abaixo desse limite pode falhar em uma conexão lenta.
Um upload aceito ainda precisa ser processado. A CLI solicita apenas
youtube.upload,
que permite a inserção. Ela não solicita a autorização mais ampla necessária para inspecionar vídeos
privados ou excluí-los pela API. Depois, confira o ID retornado no YouTube Studio do canal selecionado
e aguarde o processamento antes de usar o vídeo.
Confira a cota atual de uploads do seu projeto no Google Cloud. O YouTube contabiliza uploads em um compartimento de cota separado. Um intervalo entre comandos não repõe uma cota diária. Esta configuração solicita explicitamente visibilidade privada, independentemente dos padrões do projeto ou da conta.
Instalar as bibliotecas Python
Use um interpretador CPython 3.14 instalado com venv e pip disponíveis.
O interpretador testado é o 3.14.8; para uma nova instalação, use o patch de segurança atual da linha
3.14, que recebe manutenção, disponível nos downloads do Python.
O Python 3.15 é mais recente, mas o escopo testado deste guia é o 3.14, que o
cliente da API do Google lista explicitamente como compatível.
Execute isto no diretório pai em que você quer criar um novo diretório
youtube-cli. O subshell mantém seu diretório atual e as opções do shell intactos.
Um diretório existente é recusado. Se a instalação falhar, inspecione o erro e o diretório parcial
antes de escolher um novo local; os comandos não removem arquivos existentes.
(
set -eu
command -v python3.14 >/dev/null
mkdir youtube-cli
python3.14 -m venv youtube-cli/.venv
youtube-cli/.venv/bin/python -m pip --isolated install \
google-api-python-client==2.201.0 google-auth-oauthlib==1.5.0 \
google-auth==2.62.1 httplib2==0.32.1 requests==2.34.2
)
Estas são versões de pacotes testadas. O cliente do Google recebe manutenção para correções e fornece a API do YouTube baseada em descoberta. A pequena camada de transporte com Requests abaixo torna explícito o comportamento de novas tentativas: uma inserção que falha nunca é reiniciada automaticamente como outra inserção.
Configurar o OAuth para desktop
Use uma conta do Google que seja proprietária do canal do YouTube desejado. Siga a configuração de OAuth para desktop do Google:
- Selecione seu projeto no Google Cloud Console e ative a YouTube Data API v3.
- Configure as informações de consentimento e o público do app. Para um app externo em teste, adicione sua conta do Google como usuário de teste.
- Crie um cliente OAuth com o tipo de aplicativo Desktop app.
Baixe o JSON dele como
youtube-cli/client_secrets.json. Mantenha-o fora do controle de versão. - Encontre o ID do canal desejado nas
configurações avançadas da conta do YouTube.
Use esse ID
UC…no comando abaixo. Um identificador como@examplenão é um ID de canal.
O programa usa uma porta de loopback aleatória e PKCE. Ele solicita um novo consentimento a cada execução, não armazena cache de tokens e pede que você confirme o canal antes de inserir qualquer coisa. Escolha o canal desejado durante o fluxo de autorização do Google, incluindo a conta de marca correta quando aplicável. Digitar um ID não seleciona um canal: a conta autorizada determina o destino. O ID do canal retornado é verificado após a inserção; uma divergência é uma falha, mas pode já ter criado um vídeo privado no outro canal.
Gerenciar os metadados do vídeo
Salve isto como youtube-cli/metadata.json, substituindo o título e a descrição. Defina
madeForKids de acordo com seu público real. Essas quatro chaves compõem toda a
interface de metadados; chaves desconhecidas são recusadas. A privacidade e as notificações são fixas
no programa, em vez de serem herdadas de um arquivo auxiliar ou do padrão de uma ferramenta.
{
"title": "My command-line upload",
"description": "A completed local video.\nUploaded privately for review.",
"tags": ["demo", "command-line"],
"madeForKids": false
}
Salvar e executar a ferramenta de upload
Salve o programa completo como youtube-cli/upload.py. Ele lê o arquivo sem alterá-lo nem
alterar o arquivo auxiliar de metadados. Erros de rede após o início da inserção são tratados como
resultados incertos. Ele imprime um ID retornado em stderr antes de verificar os metadados da
resposta, para que você possa investigar uma divergência. Evite gravações compartilhadas do terminal:
a URL de autorização e o callback fazem parte de um login privado.
import argparse
import contextlib
import json
import logging
import os
import re
import signal
import stat
import sys
from urllib.parse import urlsplit
import httplib2
import requests
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.http import MediaIoBaseUpload
from requests.adapters import HTTPAdapter
UPLOAD_SCOPE = 'https://www.googleapis.com/auth/youtube.upload'
MAX_BYTES = 64 * 1024 * 1024
class UserError(Exception):
pass
def stop_at_deadline(*_):
raise UserError('The five-minute deadline expired')
class UploadTransport:
def __init__(self, credentials):
self.session = requests.Session()
self.session.trust_env = False
self.session.mount('https://', HTTPAdapter(max_retries=0))
credentials.apply(self.session.headers)
def request(self, uri, method='GET', body=None, headers=None, **_):
target = urlsplit(uri)
if (target.scheme != 'https' or target.hostname not in
('www.googleapis.com', 'youtube.googleapis.com') or
target.username is not None or target.port not in (None, 443)):
raise UserError('Unexpected upload destination')
response = self.session.request(
method, uri, data=body, headers=headers,
timeout=(10, 30), allow_redirects=False)
if 300 <= response.status_code < 400 and response.status_code != 308:
raise UserError('Upload redirect refused')
return (httplib2.Response(dict(response.headers,
status=str(response.status_code))),
response.content)
def close(self):
self.session.close()
class TimedFlow(InstalledAppFlow):
def fetch_token(self, **kwargs):
return super().fetch_token(timeout=(10, 30), **kwargs)
def authorize(config):
installed = config.get('installed', {})
if (installed.get('auth_uri') != 'https://accounts.google.com/o/oauth2/auth' or
installed.get('token_uri') != 'https://oauth2.googleapis.com/token'):
raise UserError('Use the downloaded Desktop client JSON')
flow = TimedFlow.from_client_config(
config, scopes=[UPLOAD_SCOPE], autogenerate_code_verifier=True)
flow.oauth2session.trust_env = False
flow.oauth2session.mount('https://', HTTPAdapter(max_retries=0))
def refuse_token_redirect(url, headers, request_kwargs):
return url, headers, dict(request_kwargs, allow_redirects=False)
flow.oauth2session.register_compliance_hook('access_token_request', refuse_token_redirect)
try:
if flow.oauth2session.token:
raise UserError('Expected a fresh authorization flow')
with contextlib.redirect_stdout(sys.stderr):
credentials = flow.run_local_server(
host='127.0.0.1', port=0, open_browser=False, timeout_seconds=180,
prompt='consent select_account', include_granted_scopes='false',
access_type='online')
with requests.Session() as check:
check.trust_env = False
response = check.get('https://oauth2.googleapis.com/tokeninfo',
params={'access_token': credentials.token},
timeout=(10, 30), allow_redirects=False)
if response.status_code != 200:
raise UserError('Could not check the new grant')
info = response.json()
if (info.get('aud') != installed['client_id'] or
set(info.get('scope', '').split()) != {UPLOAD_SCOPE} or
int(info.get('expires_in', 0)) < 600):
raise UserError('The new grant must be upload-only and unexpired')
return credentials
finally:
flow.oauth2session.close()
def read_metadata(filename):
with open(filename, encoding='utf-8') as source:
metadata = json.load(source)
if not isinstance(metadata, dict) or set(metadata) != {
'title', 'description', 'tags', 'madeForKids'}:
raise UserError('Metadata needs title, description, tags, and madeForKids only')
title, description, tags = (metadata[key] for key in ('title', 'description', 'tags'))
if not isinstance(title, str) or not title.strip() or len(title) > 100:
raise UserError('Title must contain 1–100 characters')
if not isinstance(description, str) or not isinstance(tags, list) or not all(
isinstance(tag, str) for tag in tags):
raise UserError('Description must be text and tags must be a list of strings')
if type(metadata['madeForKids']) is not bool:
raise UserError('madeForKids must be a JSON boolean')
return {'snippet': {'title': title, 'description': description, 'tags': tags},
'status': {'privacyStatus': 'private',
'selfDeclaredMadeForKids': metadata['madeForKids']}}
def main():
parser = argparse.ArgumentParser(description='Upload one private MP4; no automatic retry')
parser.add_argument('--file', required=True)
parser.add_argument('--metadata', required=True)
parser.add_argument('--channel-id', required=True)
parser.add_argument('--client-secrets', required=True,
help='Desktop JSON filename, or - for one private JSON line on stdin')
args = parser.parse_args()
if not re.fullmatch(r'UC[A-Za-z0-9_-]{22}', args.channel_id):
raise UserError('Expected a UC channel ID')
for filename in (args.file, args.metadata, args.client_secrets):
os.fsencode(filename).decode('utf-8', errors='strict')
body = read_metadata(args.metadata)
with open(args.file, 'rb') as media:
details = os.fstat(media.fileno())
if (not stat.S_ISREG(details.st_mode) or not 0 < details.st_size <= MAX_BYTES or
not args.file.lower().endswith('.mp4')):
raise UserError('Use a completed, nonempty MP4 of at most 64 MiB')
if args.client_secrets == '-':
config = json.loads(sys.stdin.readline())
else:
with open(args.client_secrets, encoding='utf-8') as source:
config = json.load(source)
credentials = authorize(config)
print(f'Confirm the channel selected in your browser: {args.channel_id}', file=sys.stderr)
print('Type that channel ID to insert the private video:', file=sys.stderr, flush=True)
if sys.stdin.readline().strip() != args.channel_id:
raise UserError('Channel confirmation did not match; no insert attempted')
transport = UploadTransport(credentials)
try:
youtube = build('youtube', 'v3', http=transport,
static_discovery=True, cache_discovery=False)
request = youtube.videos().insert(
part='snippet,status', body=body, notifySubscribers=False,
media_body=MediaIoBaseUpload(media, mimetype='video/mp4',
chunksize=8 * 1024 * 1024, resumable=True))
print('Insert starting; inspect the channel before retrying any failure.',
file=sys.stderr, flush=True)
result = None
while result is None:
_, result = request.next_chunk(num_retries=0)
video_id = result.get('id')
if not isinstance(video_id, str) or not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
raise UserError('YouTube did not return a native video ID')
print(f'Returned video ID: {video_id}', file=sys.stderr, flush=True)
if (result.get('snippet', {}).get('channelId') != args.channel_id or
result.get('snippet', {}).get('title') != body['snippet']['title'] or
result.get('status', {}).get('privacyStatus') != 'private'):
raise UserError('Returned metadata did not match; inspect the returned ID')
print(json.dumps({'id': video_id, 'channelId': args.channel_id,
'status': 'accepted_processing_unchecked'}), flush=True)
finally:
transport.close()
if __name__ == '__main__':
logging.disable(logging.CRITICAL)
signal.signal(signal.SIGALRM, stop_at_deadline)
signal.alarm(300)
try:
main()
except (Exception, KeyboardInterrupt) as error:
if isinstance(error, UserError):
print(str(error), file=sys.stderr)
print('Upload not confirmed. If insertion started, the video may exist. '
'Inspect your channel in YouTube Studio before another upload. '
'Check local files, metadata, authorization, and quota.', file=sys.stderr)
sys.exit(1)
finally:
signal.alarm(0)
Coloque seu arquivo concluído em ./video.mp4 e substitua
YOUR_CHANNEL_ID pelo ID do canal que você anotou. Execute isto no mesmo diretório pai
usado para o comando de instalação:
youtube-cli/.venv/bin/python youtube-cli/upload.py \
--file './video.mp4' \
--metadata youtube-cli/metadata.json \
--client-secrets youtube-cli/client_secrets.json \
--channel-id YOUR_CHANNEL_ID
Abra o link de autorização impresso no navegador local. Conclua o consentimento em até três minutos
e digite o ID do canal selecionado no prompt do terminal. O único resultado em stdout em caso de
sucesso é um JSON contendo um id nativo, o
channelId correspondente e "status": "accepted_processing_unchecked". Um código de saída
diferente de zero, um ID ausente ou uma divergência de metadados é uma falha. Guarde o ID antes de
sair do terminal; o programa não grava um comprovante local de upload.
Fazer upload de arquivos adicionais
Para vários vídeos, execute o mesmo comando uma vez para cada arquivo explícito e seu arquivo de
metadados correspondente. Mantenha os caminhos entre aspas, incluindo espaços e pontuação do shell;
use o prefixo ./ em nomes de arquivo que comecem com hífen.
O programa não descobre arquivos por padrões glob nem deriva títulos de nomes de arquivo. Cada
chamada exige novo consentimento no navegador e confirmação do canal. Pare na primeira falha e
investigue seu resultado antes de iniciar outra inserção.
Integração de upload automatizado
Um programa produtor pode invocar esta CLI após fechar um MP4 concluído, mas a autorização continua interativa. Ela não é um agendador sem supervisão. Reter tokens de atualização e adicionar um registro persistente de tarefas e IDs exigiria um projeto separado. Em especial, não coloque este comando em um loop de novas tentativas: a perda da resposta final pode deixar um vídeo no YouTube mesmo que o comando retorne falha. Este exemplo não persiste a URL de uma sessão retomável nem a recupera após o encerramento do processo.
Solucionar problemas comuns
Limites de transferência
O teto de 64 MiB é o limite deste exemplo, não o máximo da plataforma YouTube. A camada de transporte com Requests usa tempos limite de conexão de dez segundos e de leitura de 30 segundos para cada requisição, com um alarme de processo separado de cinco minutos que abrange consentimento e transferência. Ela não tem limitador de largura de banda. Se o tempo limite for atingido após o início da inserção, inspecione o canal em vez de tratar o tempo esgotado como prova de que nenhum upload foi feito.
Problemas de autenticação
Use credenciais de desktop e mantenha o navegador na máquina que executa o comando para que o
callback de loopback alcance o processo de escuta. Se o consentimento for recusado, confira o público
do app, o acesso do usuário de teste e a API ativada. A CLI deliberadamente não reutiliza um cache
de tokens. Um escopo concedido que não seja exatamente youtube.upload é recusado;
use um cliente de desktop dedicado para esse fluxo de trabalho restrito, em vez de ampliar as
permissões solicitadas.
Erros de rede e da API
A validação local ocorre antes do consentimento. Confira primeiro o caminho do arquivo e os tipos dos metadados. Após a mensagem de início da inserção, uma falha de rede ou da API exige investigação no YouTube Studio do canal selecionado. Se um ID retornado tiver sido impresso, use esse ID exato. Uma falha de processamento é diferente da aceitação da transferência; a API descreve esses estados no recurso de vídeo. Corrija a causa antes de decidir se deve enviar um novo upload.
Prefere não executar isso por conta própria?
A Transloadit codifica vídeos por meio de uma única API, sem precisar manter servidores FFmpeg em execução.
