Chame a API de Dados do YouTube v3 com curl + jq. O token OAuth do usuário está em $GOOGLE_YOUTUBE_TOKEN; toda chamada precisa dele como Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN. URL base: https://www.googleapis.com/youtube/v3.
O token sempre carrega youtube.readonly mais escopos de identidade (openid email profile); se o usuário optou por isso na instalação, também carrega youtube.upload (publicar vídeos).
As respostas são JSON padrão; falhas aparecem como {"error": {"code": 401|403|..., "message": "..."}} — mostre esse erro literalmente. 401 → token expirado, o usuário deve reconectar o conector do YouTube. 403 insufficientPermissions em um upload → o usuário não concedeu youtube.upload; peça para reconectar com a caixa de upload marcada.
Sempre comece com a verificação do canal para confirmar que a conexão funciona e descobrir contra qual canal você está operando.
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true" \
| jq '.items[0] | {title: .snippet.title, subs: .statistics.subscriberCount, views: .statistics.viewCount, uploads: .contentDetails.relatedPlaylists.uploads}'
Pesquisar no YouTube
# Pesquisa pública (qualquer vídeo). type pode ser video|channel|playlist.
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
--data-urlencode "q=automação de vídeo com ia" \
--data-urlencode "part=snippet" \
--data-urlencode "type=video" \
--data-urlencode "maxResults=10" \
-G "https://www.googleapis.com/youtube/v3/search" \
| jq '.items[] | {videoId: .id.videoId, title: .snippet.title, channel: .snippet.channelTitle, published: .snippet.publishedAt}'
Adicione --data-urlencode "order=date|viewCount|rating|relevance" para ordenar, ou --data-urlencode "publishedAfter=2026-01-01T00:00:00Z" para filtrar por data.
Ver meus vídeos enviados
O YouTube não tem uma chamada "listar meus vídeos" diretamente — leia a playlist de uploads do canal e depois pagine seus itens.
# 1. Obter o ID da playlist de uploads (UU... ) — mesma chamada do canal acima.
UPLOADS=$(curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=contentDetails&mine=true" \
| jq -r '.items[0].contentDetails.relatedPlaylists.uploads')
# 2. Listar uploads recentes (50/página; siga .nextPageToken para mais).
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/playlistItems" \
--data-urlencode "part=snippet,contentDetails" \
--data-urlencode "playlistId=$UPLOADS" \
--data-urlencode "maxResults=50" \
| jq '.items[] | {videoId: .contentDetails.videoId, title: .snippet.title, published: .snippet.publishedAt}'
Paginação: passe --data-urlencode "pageToken=$PAGE_TOKEN" com o .nextPageToken da resposta anterior.
Estatísticas do vídeo (visualizações / curtidas / comentários)
# Aceita uma lista de IDs separados por vírgula.
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/videos" \
--data-urlencode "part=snippet,statistics,status" \
--data-urlencode "id=ID_DO_VIDEO_1,ID_DO_VIDEO_2" \
| jq '.items[] | {title: .snippet.title, views: .statistics.viewCount, likes: .statistics.likeCount, comments: .statistics.commentCount, privacy: .status.privacyStatus}'
Ler comentários de um vídeo
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/commentThreads" \
--data-urlencode "part=snippet" \
--data-urlencode "videoId=ID_DO_VIDEO" \
--data-urlencode "maxResults=20" \
--data-urlencode "order=relevance" \
| jq '.items[] | .snippet.topLevelComment.snippet | {author: .authorDisplayName, text: .textDisplay, likes: .likeCount}'
Enviar um vídeo (precisa de youtube.upload)
Confirme com o usuário antes de publicar — mostre o título, a privacidade e o arquivo que você está prestes a enviar. Uploads são um fluxo retomável de duas etapas: iniciar com metadados → PUT os bytes.
ARQUIVO="/caminho/para/video.mp4"
TITULO="Meu título"
DESC="Minha descrição"
# privacyStatus: public | unlisted | private
read -r -d '' META <<JSON
{"snippet":{"title":"$TITULO","description":"$DESC","categoryId":"22"},
"status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}}
JSON
# 1. Iniciar sessão retomável -> capturar a URL de upload do cabeçalho Location.
UPLOAD_URL=$(curl -sS -D - -o /dev/null \
-H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "X-Upload-Content-Type: video/*" \
-X POST "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status" \
-d "$META" | tr -d '\r' | awk '/^[Ll]ocation:/{print $2}')
# 2. Enviar os bytes -> retorna o recurso de vídeo criado (tem .id).
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: video/*" \
-X PUT --upload-file "$ARQUIVO" "$UPLOAD_URL" \
| jq '{id: .id, url: ("https://www.youtube.com/watch?v=" + .id), privacy: .status.privacyStatus}'
categoryId 22 = "Pessoas e blogs" (um padrão seguro). Para definir uma miniatura personalizada (precisa que o arquivo seja processado primeiro), chame POST /upload/youtube/v3/thumbnails/set?videoId=ID_DO_VIDEO com a imagem.
Armadilhas
- Cota: a API de Dados tem cota (padrão 10.000 unidades/dia). Uma
searchcusta 100 unidades; umuploadcusta ~1.600. Uma rajada de pesquisas pode esgotar a cota diária →403 quotaExceeded; mostre isso claramente. - Sem endpoint "meus vídeos" — sempre vá pela playlist de uploads.
- Resultados de
searchsão eventualmente consistentes — um vídeo recém-enviado pode não aparecer emsearchpor minutos/horas; leia-o pela playlist de uploads ou pelo ID. - Vídeos enviados começam no estado
uploaded/processing; as estatísticas são0até que o processamento termine.