Llama a la API de Datos v3 de YouTube con curl + jq. El token OAuth del usuario está en $GOOGLE_YOUTUBE_TOKEN; cada llamada necesita Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN. URL base: https://www.googleapis.com/youtube/v3.
El token siempre incluye youtube.readonly más los ámbitos de identidad (openid email profile); si el usuario lo ha autorizado durante la instalación, también incluye youtube.upload (publicar videos).
Las respuestas son JSON estándar; los fallos aparecen como {"error": {"code": 401|403|..., "message": "..."}} — muestra ese error textualmente. 401 → token caducado, el usuario debe reconectar el conector de YouTube. 403 insufficientPermissions en una subida → el usuario no otorgó youtube.upload; pídele que reconecte con la casilla de subida marcada.
Comienza siempre con la verificación del canal para confirmar que la conexión funciona y saber con qué canal estás 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}'
Buscar en YouTube
# Búsqueda pública (cualquier video). type puede ser video|channel|playlist.
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
--data-urlencode "q=AI video automation" \
--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}'
Añade --data-urlencode "order=date|viewCount|rating|relevance" para ordenar, o --data-urlencode "publishedAfter=2026-01-01T00:00:00Z" para filtrar por fecha.
Ver mis videos subidos
YouTube no tiene una llamada directa "listar mis videos" — hay que leer la lista de reproducción de subidas del canal y luego paginar sus elementos.
# 1. Obtener el ID de la lista de reproducción de subidas (UU... ) — igual que la llamada de canales anterior.
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 las subidas recientes (50/página; sigue .nextPageToken para más).
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}'
Paginación: pasa --data-urlencode "pageToken=$PAGE_TOKEN" con el .nextPageToken de la respuesta anterior.
Estadísticas de video (vistas / likes / comentarios)
# Acepta una lista de IDs separados por comas.
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=VIDEO_ID_1,VIDEO_ID_2" \
| jq '.items[] | {title: .snippet.title, views: .statistics.viewCount, likes: .statistics.likeCount, comments: .statistics.commentCount, privacy: .status.privacyStatus}'
Leer comentarios de un video
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/commentThreads" \
--data-urlencode "part=snippet" \
--data-urlencode "videoId=VIDEO_ID" \
--data-urlencode "maxResults=20" \
--data-urlencode "order=relevance" \
| jq '.items[] | .snippet.topLevelComment.snippet | {author: .authorDisplayName, text: .textDisplay, likes: .likeCount}'
Subir un video (necesita youtube.upload)
Confirma con el usuario antes de publicar — muestra el título, la privacidad y el archivo que vas a subir. Las subidas siguen un flujo reanudable de dos pasos: iniciar con metadatos → PUT los bytes.
ARCHIVO="/ruta/al/video.mp4"
TITULO="Mi título"
DESC="Mi descripción"
# privacyStatus: public | unlisted | private
read -r -d '' META <<JSON
{"snippet":{"title":"$TITULO","description":"$DESC","categoryId":"22"},
"status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}}
JSON
# 1. Iniciar sesión reanudable -> capturar la URL de subida del encabezado 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. Subir los bytes -> devuelve el recurso de video creado (tiene .id).
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: video/*" \
-X PUT --upload-file "$ARCHIVO" "$UPLOAD_URL" \
| jq '{id: .id, url: ("https://www.youtube.com/watch?v=" + .id), privacy: .status.privacyStatus}'
categoryId 22 = "Personas y Blogs" (un valor seguro por defecto). Para establecer una miniatura personalizada (necesita que el archivo se haya procesado primero), llama a POST /upload/youtube/v3/thumbnails/set?videoId=VIDEO_ID con la imagen.
Advertencias
- Cuota: la API de Datos tiene límite de cuota (por defecto 10,000 unidades/día). Una
searchcuesta 100 unidades; unauploadcuesta ~1,600. Una ráfaga de búsquedas puede agotar la cuota diaria →403 quotaExceeded; indícalo claramente. - No existe un endpoint "mis videos" — siempre ve a través de la lista de reproducción de subidas.
- Los resultados de
searchson eventualmente consistentes — un video recién subido puede no aparecer ensearchdurante minutos/horas; léelo mediante la lista de reproducción de subidas o por ID. - Los videos subidos comienzan en estado
uploaded/processing; las estadísticas son0hasta que se completa el procesamiento.