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
- Ir a Google Cloud Console
- Crear un proyecto nuevo o seleccionar uno existente
- Habilitar la API de datos de YouTube v3
- Crear credenciales → Clave de API
- (Opcional) Restringir la clave de API solo a la API de datos de YouTube
Límites de cuota
| Tipo de operación | Costo de cuota (unidades) |
|---|---|
| Operaciones de lectura (listar) | 1 |
| Solicitudes de búsqueda | 100 |
| Operaciones de escritura (insertar/actualizar/eliminar) | 50 |
| Subida de video | 1600 |
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ámetro | Descripción | Valores |
|---|---|---|
--query, -q | Palabras clave de búsqueda | Admite operadores booleanos (python AND tutorial) |
--type | Tipo de recurso | video, channel, playlist |
--max-results | Cantidad de resultados | 1-50, por defecto 25 |
--order | Orden de clasificación | relevance(predeterminado), date, rating, viewCount, title |
--published-after | Publicado después de | 1d, 7d, 30d, 1y o formato ISO 8601 |
--published-before | Publicado antes de | Igual que el anterior |
--region-code | Código de región | ISO 3166-1 (p. ej., US, CN, JP) |
--relevance-language | Idioma | ISO 639-1 (p. ej., en, zh, ja) |
--video-duration | Duración del video | short(<4min), medium(4-20min), long(>20min) |
--video-definition | Definición | high(HD), standard(SD) |
--video-caption | Subtítulos | closedCaption(tiene subtítulos), none(sin subtítulos) |
--video-dimension | Dimensión | 2d, 3d |
--event-type | Estado de transmisión en vivo | live(transmitiendo), completed(finalizado), upcoming(programado) |
--channel-id | Limitar a un canal | ID del canal |
--safe-search | Búsqueda segura | none, 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
| Parte | Contiene |
|---|---|
snippet | Título, descripción, miniaturas, información del canal, hora de publicación, etiquetas |
statistics | Recuento de vistas, recuento de 'me gusta', recuento de comentarios |
contentDetails | Duración, definición, información de subtítulos, restricciones regionales |
status | Estado de subida, privacidad, licencia |
player | HTML del reproductor incrustado |
topicDetails | IDs de temas relacionados |
recordingDetails | Ubicación de grabación, fecha |
liveStreamingDetails | Información en vivo (hora de inicio/fin, recuento de espectadores) |
Referencia de IDs de categoría de video
| ID | Categoría | ID | Categoría |
|---|---|---|---|
| 1 | Cine y animación | 20 | Videojuegos |
| 2 | Autos y vehículos | 22 | Personas y blogs |
| 10 | Música | 23 | Comedia |
| 15 | Mascotas y animales | 24 | Entretenimiento |
| 17 | Deportes | 25 | Noticias y política |
| 19 | Viajes y eventos | 26 | Cómo se hace y estilo |
| 27 | Educación | 28 | Ciencia 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
| Parte | Contiene |
|---|---|
snippet | Nombre del canal, descripción, miniaturas, país |
statistics | Recuento de suscriptores, recuento de videos, vistas totales |
contentDetails | Listas de reproducción relacionadas (subidas, favoritos, etc.) |
brandingSettings | Banner del canal, palabras clave, idioma predeterminado |
topicDetails | Temas del canal |
status | Estado 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
| Orden | Descripción |
|---|---|
relevance | Por relevancia (predeterminado) |
time | Por 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ódigo | Descripción | Solución |
|---|---|---|
| 400 | Solicitud incorrecta | Verificar el formato del parámetro |
| 401 | No autorizado | Verificar la clave de API |
| 403 | Cuota excedida o permisos insuficientes | Verificar la cuota o solicitar un aumento |
| 404 | Recurso no encontrado | Verificar que el ID sea correcto |
| 429 | Demasiadas solicitudes | Reducir la frecuencia de solicitudes |
Consejos para optimizar la cuota
- Usar el parámetro
fieldspara solicitar solo los campos necesarios - Solicitudes por lotes usando listas de IDs separadas por comas
- Almacenar en caché los resultados para evitar solicitudes duplicadas
- 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"