Communitygithub.com

Yrzhe/claude-skills

Wrapper completo de la API de datos de YouTube v3: busca videos, obtén detalles de videos/canales/listas de reproducción, comentarios, descarga subtítulos y más. Admite filtrado y ordenación por tiempo, vistas, calificación, etc.

¿Qué es claude-skills?

Esta habilidad proporciona un envoltorio completo y de alto nivel sobre la API de datos de YouTube v3, permitiendo a agentes de IA (como Claude Code, Cursor o Codex) interactuar con YouTube de manera programática. Es útil para desarrolladores o agentes que necesitan buscar videos, obtener estadísticas detalladas de videos y canales, recuperar listas de reproducción y sus elementos, analizar comentarios, descargar subtítulos (con opciones alternativas como yt-dlp) y consultar categorías o regiones compatibles. La habilidad se configura mediante una clave de API de Google Cloud (almacenada como variable de entorno o en un archivo de configuración) y requiere respetar los límites de cuota de la API, documentando claramente el costo en unidades de cada operación. Su interfaz basada en línea de comandos (scripts de Python) permite filtrar y ordenar resultados por múltiples criterios (tiempo de publicación, vistas, duración del video, región, etc.), paginar resultados, formatear la salida en JSON, CSV o texto simple, y manejar errores comunes de la API.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yrzhe/claude-skills/tree/HEAD/plugins/youtube-data-api/skills/youtube-data-api

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad de la API de datos de YouTube v3

Wrapper completo basado en la documentación oficial de la API de datos de YouTube v3.

Configuración

Configuración de la clave de API

# Opción 1: Variable de entorno (recomendada)
export YOUTUBE_API_KEY="TU_CLAVE_API_AQUÍ"

# Opción 2: Editar el archivo de configuración directamente
# Editar ~/.claude/skills/youtube-data-api/scripts/config.py

Cómo obtener una clave de API

  1. Ir a Google Cloud Console
  2. Crear un proyecto nuevo o seleccionar uno existente
  3. Habilitar la API de datos de YouTube v3
  4. Crear credenciales → Clave de API
  5. (Opcional) Restringir la clave de API solo a la API de datos de YouTube

Límites de cuota

Tipo de operaciónCosto de cuota (unidades)
Operaciones de lectura (listar)1
Solicitudes de búsqueda100
Operaciones de escritura (insertar/actualizar/eliminar)50
Subida de video1600

Cuota diaria predeterminada: 10,000 unidades


Funcionalidades principales

1. Buscar videos (Search)

Costo de cuota: 100 unidades/solicitud

# Búsqueda básica
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Tutorial de Python" \
    --max-results 25

# Filtrar por tiempo (última semana)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "aprendizaje automático" \
    --published-after "7d" \
    --type video

# Ordenar por recuento de vistas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "React hooks" \
    --order viewCount \
    --type video

# Solo videos HD
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "naturaleza 4K" \
    --video-definition high \
    --type video

# Videos con subtítulos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "charla TED" \
    --video-caption closedCaption \
    --type video

# Videos en transmisión en vivo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "videojuegos" \
    --event-type live \
    --type video

# Filtrar por región
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "noticias" \
    --region-code US \
    --relevance-language en

# Filtrar por duración del video
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "documental" \
    --video-duration long \
    --type video

Referencia de parámetros de búsqueda

ParámetroDescripciónValores
--query, -qPalabras clave de búsquedaAdmite operadores booleanos (python AND tutorial)
--typeTipo de recursovideo, channel, playlist
--max-resultsCantidad de resultados1-50, por defecto 25
--orderOrden de clasificaciónrelevance(predeterminado), date, rating, viewCount, title
--published-afterPublicado después de1d, 7d, 30d, 1y o formato ISO 8601
--published-beforePublicado antes deIgual que el anterior
--region-codeCódigo de regiónISO 3166-1 (p. ej., US, CN, JP)
--relevance-languageIdiomaISO 639-1 (p. ej., en, zh, ja)
--video-durationDuración del videoshort(<4min), medium(4-20min), long(>20min)
--video-definitionDefiniciónhigh(HD), standard(SD)
--video-captionSubtítulosclosedCaption(tiene subtítulos), none(sin subtítulos)
--video-dimensionDimensión2d, 3d
--event-typeEstado de transmisión en vivolive(transmitiendo), completed(finalizado), upcoming(programado)
--channel-idLimitar a un canalID del canal
--safe-searchBúsqueda seguranone, moderate, strict

2. Obtener detalles del video (Videos)

Costo de cuota: 1 unidad/solicitud

# Obtener detalles de un solo video
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ" \
    --parts snippet,statistics,contentDetails

# Obtener múltiples videos (lote)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ,jNQXAC9IVRw,9bZkp7q19f0" \
    --parts snippet,statistics

# Obtener videos en tendencia
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --region-code US \
    --max-results 50

# Obtener tendencias por categoría
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --video-category-id 10 \
    --region-code JP

Referencia de partes de video

ParteContiene
snippetTítulo, descripción, miniaturas, información del canal, hora de publicación, etiquetas
statisticsRecuento de vistas, recuento de 'me gusta', recuento de comentarios
contentDetailsDuración, definición, información de subtítulos, restricciones regionales
statusEstado de subida, privacidad, licencia
playerHTML del reproductor incrustado
topicDetailsIDs de temas relacionados
recordingDetailsUbicación de grabación, fecha
liveStreamingDetailsInformación en vivo (hora de inicio/fin, recuento de espectadores)

Referencia de IDs de categoría de video

IDCategoríaIDCategoría
1Cine y animación20Videojuegos
2Autos y vehículos22Personas y blogs
10Música23Comedia
15Mascotas y animales24Entretenimiento
17Deportes25Noticias y política
19Viajes y eventos26Cómo se hace y estilo
27Educación28Ciencia y tecnología

3. Obtener información del canal (Channels)

Costo de cuota: 1 unidad/solicitud

# Obtener por ID de canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --parts snippet,statistics,contentDetails

# Obtener por nombre de usuario
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-username "GoogleDevelopers" \
    --parts snippet,statistics

# Obtener por identificador (@nombredeusuario)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@Google" \
    --parts snippet,statistics,brandingSettings

Referencia de partes de canal

ParteContiene
snippetNombre del canal, descripción, miniaturas, país
statisticsRecuento de suscriptores, recuento de videos, vistas totales
contentDetailsListas de reproducción relacionadas (subidas, favoritos, etc.)
brandingSettingsBanner del canal, palabras clave, idioma predeterminado
topicDetailsTemas del canal
statusEstado del canal (permiso de subida de videos largos, etc.)

4. Obtener listas de reproducción (Playlists)

Costo de cuota: 1 unidad/solicitud

# Obtener lista de reproducción por ID
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --parts snippet,contentDetails

# Obtener todas las listas de reproducción de un canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

5. Obtener videos de una lista de reproducción (PlaylistItems)

Costo de cuota: 1 unidad/solicitud

# Obtener todos los videos de una lista de reproducción
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --max-results 50

# Recuperación paginada
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --page-token "TOKEN_SIGUIENTE_PAGINA"

6. Obtener comentarios (Comments & CommentThreads)

Costo de cuota: 1 unidad/solicitud

# Obtener todos los comentarios de un video (nivel superior)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "dQw4w9WgXcQ" \
    --max-results 100 \
    --order relevance

# Obtener comentarios de un canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

# Obtener respuestas a un comentario
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comment-replies \
    --parent-id "ID_DEL_COMENTARIO" \
    --max-results 50

Opciones de ordenación de comentarios

OrdenDescripción
relevancePor relevancia (predeterminado)
timePor hora (los más nuevos primero)

7. Obtener subtítulos (Captions)

Costo de cuota: 1 unidad/solicitud (listar), 50 unidades (descargar)

# Listar todas las pistas de subtítulos de un video
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --list

# Descargar subtítulos (requiere OAuth)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --download \
    --caption-id "ID_DE_SUBTITULO" \
    --format srt

Nota: Descargar subtítulos requiere autorización del propietario del video (OAuth). Para videos públicos, use yt-dlp para obtener subtítulos generados automáticamente.

Usando yt-dlp para subtítulos (Alternativa)

# Instalar yt-dlp
pip install yt-dlp

# Listar subtítulos disponibles
yt-dlp --list-subs "https://www.youtube.com/watch?v=ID_DEL_VIDEO"

# Descargar subtítulos (saltar video)
yt-dlp --write-sub --write-auto-sub --sub-lang en,zh-Hans --skip-download \
    "https://www.youtube.com/watch?v=ID_DEL_VIDEO"

# Descargar y convertir al formato SRT
yt-dlp --write-sub --write-auto-sub --sub-lang en --sub-format srt --skip-download \
    "https://www.youtube.com/watch?v=ID_DEL_VIDEO"

8. Obtener categorías de video (VideoCategories)

Costo de cuota: 1 unidad/solicitud

# Obtener categorías de video para una región
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code US

# Obtener categorías para China
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code CN

9. Obtener regiones e idiomas compatibles

Costo de cuota: 1 unidad/solicitud

# Obtener lista de regiones compatibles
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py regions

# Obtener lista de idiomas compatibles
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py languages

Ejemplos de casos de uso comunes

Escenario 1: Obtener videos en tendencia sobre un tema de la última semana

# Buscar videos sobre "IA" de los últimos 7 días, ordenados por recuento de vistas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "IA inteligencia artificial" \
    --published-after "7d" \
    --order viewCount \
    --type video \
    --max-results 50 \
    --output ia_tendencias.json

# Obtener estadísticas detalladas de estos videos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --ids-from ia_tendencias.json \
    --parts snippet,statistics,contentDetails \
    --output ia_tendencias_detalles.json

Escenario 2: Analizar todos los videos de un canal

# 1. Obtener información del canal
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@GoogleDevelopers" \
    --parts snippet,statistics,contentDetails \
    --output canal_info.json

# 2. Obtener ID de la lista de reproducción de subidas (desde contentDetails.relatedPlaylists.uploads)

# 3. Obtener todos los videos subidos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "ID_LISTA_SUBIDAS" \
    --max-results 50 \
    --all-pages \
    --output canal_videos.json

Escenario 3: Obtener videos con subtítulos

# 1. Buscar videos
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "charla TED motivación" \
    --video-caption closedCaption \
    --type video \
    --max-results 10 \
    --output ted_videos.json

# 2. Descargar subtítulos usando yt-dlp
for video_id in $(jq -r '.items[].id.videoId' ted_videos.json); do
    yt-dlp --write-sub --write-auto-sub --sub-lang en --skip-download \
        "https://www.youtube.com/watch?v=$video_id" \
        -o "subtitles/%(id)s.%(ext)s"
done

Escenario 4: Analizar comentarios de videos

# Obtener todos los comentarios de un video
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "ID_DEL_VIDEO" \
    --max-results 100 \
    --all-pages \
    --output comentarios.json

# Los datos de comentarios incluyen:
# - Nombre del autor
# - Texto del comentario
# - Recuento de 'me gusta'
# - Hora de publicación
# - Recuento de respuestas

Formatos de salida

Todos los comandos generan salida JSON de forma predeterminada; guarde en un archivo con el parámetro --output.

# Salida a archivo
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --output resultados.json

# Formato CSV (datos tabulares)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format csv \
    --output resultados.csv

# Salida simple (solo títulos e IDs)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format simple

Paginación

Para conjuntos de datos grandes, la API usa pageToken para la paginación:

# Obtener automáticamente todas las páginas
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --all-pages \
    --max-total 500 \
    --output todos_los_resultados.json

# Paginación manual
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --page-token "TOKEN_SIGUIENTE_PAGINA"

Manejo de errores

Códigos de error comunes

CódigoDescripciónSolución
400Solicitud incorrectaVerificar el formato del parámetro
401No autorizadoVerificar la clave de API
403Cuota excedida o permisos insuficientesVerificar la cuota o solicitar un aumento
404Recurso no encontradoVerificar que el ID sea correcto
429Demasiadas solicitudesReducir la frecuencia de solicitudes

Consejos para optimizar la cuota

  1. Usar el parámetro fields para solicitar solo los campos necesarios
  2. Solicitudes por lotes usando listas de IDs separadas por comas
  3. Almacenar en caché los resultados para evitar solicitudes duplicadas
  4. Usar ETags para verificar si un recurso ha sido actualizado
# Obtener solo los campos necesarios (reduce el tamaño de la respuesta)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "ID_DEL_VIDEO" \
    --fields "items(id,snippet(title,channelTitle),statistics(viewCount))"

Operaciones que requieren OAuth

Las siguientes operaciones requieren autorización del usuario (la clave de API por sí sola no es suficiente):

  • Subir videos
  • Actualizar metadatos de videos
  • Eliminar videos
  • Gestionar listas de reproducción
  • Publicar/comentar

Para estas operaciones, necesita configurar OAuth 2.0:

# Establecer ruta de credenciales OAuth
export YOUTUBE_OAUTH_JSON="ruta/a/credenciales_oauth.json"

# OAuth iniciará sesión en el navegador la primera vez

Referencia de la línea de comandos

Uso: youtube_api.py <comando> [opciones]

Comandos:
  search            Buscar recursos en YouTube
  video             Obtener detalles de videos
  channel           Obtener información de canales
  playlist          Obtener detalles de listas de reproducción
  playlist-items    Obtener elementos de listas de reproducción
  comments          Obtener comentarios de videos/canales
  comment-replies   Obtener respuestas a comentarios
  captions          Listar/descargar subtítulos
  categories        Obtener categorías de video
  regions           Obtener regiones compatibles
  languages         Obtener idiomas compatibles

Opciones globales:
  --output ARCHIVO     Guardar respuesta en un archivo
  --format FORMATO     Formato de salida (json, csv, simple)
  --max-results N      Número máximo de resultados (1-50)
  --all-pages          Obtener todas las páginas de resultados
  --max-total N        Número máximo de resultados al obtener todas las páginas
  --page-token TOKEN   Token para paginación
  --fields CAMPOS      Filtrar campos de respuesta
  --pretty             Salida JSON con sangría

Gestión de dependencias

El script requiere:

  • Python 3.8+
  • Módulos: requests, json (biblioteca estándar)

Instalar dependencias:

pip install requests

Para descarga de subtítulos alternativa:

pip install yt-dlp

Soporte para proxy

El script admite variables de entorno de proxy estándar:

export HTTP_PROXY="http://proxy.local:8080"
export HTTPS_PROXY="http://proxy.local:8080"

Skills relacionados