API de Archivos Gemini
Sube y gestiona archivos para usar con modelos Gemini mediante scripts ejecutables, compatible con imágenes, audio, video, PDFs 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 de 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 de Gemini
Cuándo usarlo:
- Subir cualquier archivo para procesamiento en Gemini
- Preparar archivos para generación multimodal
- Subir documentos para análisis
- Preparación de archivos por lotes
Parámetros clave:
| Parámetro | Descripción | Ejemplo |
|---|---|---|
path | Ruta del archivo (requerido) | image.jpg |
--name, -n | Nombre mostrado | "mi-documento" |
--wait, -w | Esperar a que se procese | Indicador |
Salida: Nombre del archivo, URI e información de estado
Flujos de trabajo
Flujo 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 API
- Estado: PROCESSING o ACTIVE
Flujo 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 no sea suficientemente descriptivo
- El nombre mostrado aparece en los listados de archivos
Flujo 3: Subida y espera de procesamiento
python scripts/upload.py video.mp4 --wait
- Ideal para: Archivos grandes, videos, audio
- Espera hasta que el archivo esté en estado ACTIVE
- Úsalo cuando: Necesites usar el archivo inmediatamente después de subirlo
Flujo 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, descripción, preguntas y respuestas visuales
- Se combina con: gemini-text para procesamiento multimodal
Flujo 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 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 archivos subidos (skill gemini-batch)
- Ideal para: Preparar archivos para procesamiento por lotes
- Se combina con: gemini-batch para operaciones masivas
Flujo 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 hay transcripción disponible)
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 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 tiempo de procesamiento significativo
Referencia de parámetros
Tipos de archivo soportados
| Tipo | Extensiones | Tamaño máximo | Tiempo de procesamiento |
|---|---|---|---|
| Imágenes | jpg, jpeg, png, gif, webp | 20 MB | Segundos |
| Audio | mp3, wav, aac, flac | 25 MB | Segundos a minutos |
| Video | mp4, mov, avi, webm | 2 GB | Minutos a horas |
| Documentos | pdf, txt | 50 MB | Segundos a 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 del archivo
| Estado | Descripción | Listo para usar |
|---|---|---|
PROCESSING | El archivo se está analizando | 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 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...
Todavía procesando...
¡Archivo listo!
- El script consulta hasta que el estado sea ACTIVE
- Úsalo para archivos grandes que requieren procesamiento
- Puede tomar minutos para videos
Usar archivos subidos
Una vez subidos, referencia el archivo por su 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 relativas fallan
- Comprueba que la extensión del archivo coincida con los tipos soportados
"Archivo demasiado grande"
- Revisa los límites de tamaño para el tipo de archivo
- Comprime imágenes/videos si es posible
- Divide archivos grandes en partes más pequeñas
"Tipo de archivo no soportado"
- Revisa las extensiones soportadas
- Convierte a un formato soportado si es posible
- Imágenes: jpg, png, gif, webp
- Videos: mp4, mov, avi, webm
"Procesamiento falló"
- Verifica que el archivo no esté dañado
- Intenta subir el archivo de nuevo
- Confirma que el formato del archivo sea válido
- Revisa los límites de cuota de la API
"El archivo aún se está procesando" (sin --wait)
- El estado del archivo es PROCESSING, no ACTIVE
- Usa el indicador
--waito verifica el estado más tarde - Los archivos grandes (especialmente videos) toman tiempo
- El procesamiento puede tomar de minutos a horas
Buenas prácticas
Estrategia de subida
- Usa
--waitpara archivos que usarás inmediatamente - Omite
--waiten subidas por lotes para ahorrar tiempo - Usa
--namedescriptivo para organización - Lleva un registro de los nombres de archivo para uso posterior
Organización de archivos
- Usa convenciones de nomenclatura 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 API
- Elimina archivos antiguos para gestionar el almacenamiento
Manejo de errores
- Revisa el estado devuelto después de la subida
- Reintenta subidas fallidas
- Verifica la integridad del archivo antes de subir
- Registra los nombres de archivo para 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 expirar después de cierto período
- Descarga archivos importantes para 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 del archivo
file = client.files.get(name="files/abc123...")
print(f"Estado: {file.state}")
# Eliminar archivo
client.files.delete(name="files/abc123...")
Referencia
- Obtener 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 soportados: Imágenes, audio, video, documentos (ver tabla arriba)