majiayu000/claude-skill-registry

API de Archivos Gemini

Sube y gestiona archivos para usar con modelos Gemini mediante scripts ejecutables, compatibles con imágenes, audio, video, PDF y otros tipos de archivo.

Cuándo usar este skill

Usa este skill cuando necesites:

• Subir imágenes para análisis multimodal
• Subir videos para procesamiento de contenido
• Subir PDFs para análisis de documentos
• Subir audio para transcripción o procesamiento
• Precargar archivos para operaciones por lotes
• Verificar el estado del procesamiento de archivos
• Listar y gestionar archivos subidos
• Usar archivos con otros skills de Gemini (texto, imagen, etc.)

Scripts disponibles

scripts/upload.py

Propósito: Subir archivos a la API de Archivos Gemini

Cuándo usarlo:

• Para subir cualquier archivo para procesamiento Gemini
• Para preparar archivos para generación multimodal
• Para subir documentos para análisis
• Para preparación de archivos por lotes

Parámetros clave:

Parámetro	Descripción	Ejemplo
path	Ruta del archivo (requerido)	image.jpg
--name, -n	Nombre para mostrar	"mi-documento"
--wait, -w	Esperar a que se procese	Indicador

Salida: Nombre del archivo, URI e información de estado

Flujos de trabajo

Flujo de trabajo 1: Subida básica de archivo

python scripts/upload.py image.jpg

• Ideal para: Subidas rápidas, archivos simples
• Salida: Nombre del archivo y URI para uso en la API
• Estado: PROCESSING o ACTIVE

Flujo de trabajo 2: Subida con nombre personalizado

python scripts/upload.py document.pdf --name "Informe trimestral Q4 2026"

• Ideal para: Organizar archivos, rastrear subidas
• Úsalo cuando: El nombre original del archivo no sea suficientemente descriptivo
• El nombre para mostrar aparece en los listados de archivos

Flujo de trabajo 3: Subir y esperar procesamiento

python scripts/upload.py video.mp4 --wait

• Ideal para: Archivos grandes, videos, audio
• Espera a que el archivo alcance el estado ACTIVE
• Úsalo cuando: Necesites usar el archivo inmediatamente después de subirlo

Flujo de trabajo 4: Subir imagen para análisis

# 1. Subir imagen
python scripts/upload.py photo.png --name "foto-producto"

# 2. Usar con gemini-text para análisis
python skills/gemini-text/scripts/generate.py "Describe esta imagen" --image photo.png

• Ideal para: Análisis de imágenes, subtitulado, preguntas y respuestas visuales
• Se combina con: gemini-text para procesamiento multimodal

Flujo de trabajo 5: Subir PDF para extracción de contenido

# 1. Subir PDF
python scripts/upload.py articulo-investigacion.pdf --name "Articulo-IA" --wait

# 2. Extraer contenido con gemini-text
python skills/gemini-text/scripts/generate.py "Extrae los hallazgos clave de este documento" --image articulo-investigacion.pdf

• Ideal para: Procesamiento de documentos, extracción de contenido
• Se combina con: gemini-text para análisis

Flujo de trabajo 6: Subir múltiples archivos para lote

# 1. Subir múltiples archivos
for file in *.jpg; do
    python scripts/upload.py "$file"
done

# 2. Crear trabajo por lotes usando los archivos subidos (skill gemini-batch)

• Ideal para: Preparar archivos para procesamiento por lotes
• Se combina con: gemini-batch para operaciones masivas

Flujo de trabajo 7: Subir audio para transcripción

# 1. Subir audio
python scripts/upload.py entrevista.mp3 --name "entrevista-001" --wait

# 2. Procesar con gemini-text (si está disponible la transcripción)
python skills/gemini-text/scripts/generate.py "Transcribe y resume este audio" --image entrevista.mp3

• Ideal para: Procesamiento de audio, transcripción, análisis de podcasts
• Se combina con: gemini-text para análisis de audio

Flujo de trabajo 8: Subir video para análisis de contenido

# 1. Subir video (puede llevar tiempo)
python scripts/upload.py demo-producto.mp4 --name "video-demo" --wait

# 2. Analizar con gemini-text
python skills/gemini-text/scripts/generate.py "Analiza este video de demostración del producto" --image demo-producto.mp4

• Ideal para: Análisis de video, resumen de contenido
• Nota: Los videos pueden requerir un tiempo de procesamiento significativo

Referencia de parámetros

Tipos de archivo compatibles

Tipo	Extensiones	Tamaño máximo	Tiempo de procesamiento
Imágenes	jpg, jpeg, png, gif, webp	20MB	Segundos
Audio	mp3, wav, aac, flac	25MB	Segundos-minutos
Video	mp4, mov, avi, webm	2GB	Minutos-horas
Documentos	pdf, txt	50MB	Segundos-minutos

Tipos MIME

El script detecta automáticamente según la extensión:

• Imágenes: image/jpeg, image/png, image/gif, image/webp
• Audio: audio/mpeg, audio/wav
• Video: video/mp4, video/quicktime, video/webm
• Documentos: application/pdf, text/plain

Estados de archivo

Estado	Descripción	Listo para usar
PROCESSING	El archivo está siendo analizado	No
ACTIVE	El archivo está listo	Sí
FAILED	El procesamiento falló	No

Interpretación de la salida

Respuesta de subida

Subiendo photo.png...
Subido: files/abc123...
URI: gs://generation-tmp/abc123...
Estado: PROCESSING

• Nombre del archivo: Úsalo en llamadas a la API
• URI: Referencia interna de Google Cloud Storage
• Estado: PROCESSING = esperar, ACTIVE = listo

Con el indicador --wait

Subiendo video.mp4...
Subido: files/xyz789...
URI: gs://generation-tmp/xyz789...
Estado: PROCESSING
Esperando procesamiento...
Aún procesando...
¡Archivo listo!

• El script consulta hasta que el estado sea ACTIVE
• Úsalo para archivos grandes que requieran procesamiento
• Puede tardar minutos para videos

Usando archivos subidos

Una vez subido, referencia el archivo por nombre:

# Con gemini-text
python skills/gemini-text/scripts/generate.py "Analiza" --image <ruta-archivo-subido>

Problemas comunes

"google-genai no instalado"

pip install google-genai

"Archivo no encontrado"

• Verifica que la ruta del archivo sea correcta
• Usa rutas absolutas si las rutas relativas fallan
• Comprueba que la extensión del archivo esté entre los tipos compatibles

"Archivo demasiado grande"

• Revisa los límites de tamaño según el tipo de archivo
• Comprime imágenes/videos si es posible
• Divide archivos grandes en partes más pequeñas

"Tipo de archivo no compatible"

• Revisa las extensiones compatibles
• Convierte a un formato compatible si es posible
• Imágenes: jpg, png, gif, webp
• Videos: mp4, mov, avi, webm

"Procesamiento fallido"

• Verifica que el archivo no esté corrupto
• Intenta volver a subir el archivo
• Confirma que el formato del archivo sea válido
• Revisa los límites de cuota de la API

"Archivo aún en procesamiento" (sin --wait)

• El estado del archivo es PROCESSING, no ACTIVE
• Usa el indicador --wait o verifica el estado más tarde
• Los archivos grandes (especialmente videos) tardan tiempo
• El procesamiento puede tomar de minutos a horas

Mejores prácticas

Estrategia de subida

• Usa --wait para archivos que usarás inmediatamente
• Omite --wait para subidas por lotes para ahorrar tiempo
• Usa nombres --name descriptivos para organización
• Lleva un registro de los nombres de archivo para uso posterior

Organización de archivos

• Usa convenciones de nombres consistentes
• Incluye fechas o versiones en los nombres
• Agrupa archivos relacionados
• Documenta los nombres de archivo en tu código

Consejos de rendimiento

• Sube múltiples archivos en paralelo (procesos separados)
• Precarga archivos para operaciones por lotes
• Verifica el estado del archivo antes de usarlo en llamadas a la API
• Elimina archivos antiguos para gestionar el almacenamiento

Manejo de errores

• Verifica el estado de retorno después de la subida
• Reintenta subidas fallidas
• Verifica la integridad del archivo antes de subir
• Registra los nombres de archivo para pistas de auditoría

Integración con otros skills

• gemini-text: Análisis multimodal, procesamiento de documentos
• gemini-image: Generar imágenes basadas en referencias subidas
• gemini-batch: Usar archivos subidos en trabajos por lotes
• gemini-embeddings: Crear embeddings a partir del contenido del archivo

Ciclo de vida del archivo

• Subir → PROCESSING → ACTIVE → Usar en API
• Elimina archivos antiguos para liberar almacenamiento
• Los archivos pueden caducar después de un período
• Descarga archivos importantes como respaldo

Skills relacionados

• gemini-text: Analiza archivos subidos con generación de texto
• gemini-image: Crea imágenes basadas en referencias subidas
• gemini-batch: Usa archivos subidos en procesamiento por lotes
• gemini-embeddings: Genera embeddings a partir del contenido del archivo

Referencia rápida

# Subida básica
python scripts/upload.py image.jpg

# Con nombre personalizado
python scripts/upload.py document.pdf --name "Mi Documento"

# Esperar procesamiento
python scripts/upload.py video.mp4 --wait

# Múltiples archivos
for file in *.jpg; do python scripts/upload.py "$file"; done

API de gestión de archivos

Aunque no está en los scripts, también puedes gestionar archivos mediante Python:

from google import genai

client = genai.Client()

# Listar todos los archivos
for file in client.files.list():
    print(f"{file.name}: {file.display_name} ({file.state})")

# Obtener información de un archivo
file = client.files.get(name="files/abc123...")
print(f"Estado: {file.state}")

# Eliminar archivo
client.files.delete(name="files/abc123...")

Referencia

• Obtén una clave API: https://aistudio.google.com/apikey
• Documentación: https://ai.google.dev/gemini-api/docs/file-upload
• API de archivos: https://ai.google.dev/gemini-api/docs/files
• Formatos compatibles: Imágenes, audio, video, documentos (ver tabla arriba)