API de Archivos de Gemini
Sube y gestiona archivos para usar con los modelos Gemini a través de scripts ejecutables, compatible con imágenes, audio, video, PDFs y otros tipos de archivo.
Cuándo Usar Esta Habilidad
Usa esta habilidad 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 otras habilidades 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 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 (obligatorio) | image.jpg |
--name, -n | Nombre para mostrar | "mi-documento" |
--wait, -w | Esperar a que termine el procesamiento | Bandera |
Salida: Nombre del archivo, URI e información de estado
Flujos de Trabajo
Flujo 1: Subida Básica de Archivo
python scripts/upload.py imagen.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 documento.pdf --name "Informe Trimestral Q4 2026"
- Ideal para: Organizar archivos, rastrear subidas
- Usar cuando: El nombre original del archivo no es 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
- Usar cuando: Necesitas usar el archivo inmediatamente después de subir
Flujo 4: Subir Imagen para Análisis
# 1. Subir imagen
python scripts/upload.py foto.png --name "foto-producto"
# 2. Usar con gemini-text para análisis
python skills/gemini-text/scripts/generate.py "Describe esta imagen" --image foto.png
- Ideal para: Análisis de imágenes, subtitulado, 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-Investigacion" --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 Lotes
# 1. Subir varios archivos
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. Crear trabajo por lotes usando los archivos subidos (habilidad 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 tomar 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 Soportados
| 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: Usar en llamadas API
- URI: Referencia interna de Google Cloud Storage
- Estado: PROCESSING = esperar, ACTIVE = listo
Con la Bandera --wait
Subiendo video.mp4...
Subido: files/xyz789...
URI: gs://generation-tmp/xyz789...
Estado: PROCESSING
Esperando procesamiento...
Todavía procesando...
¡Archivo listo!
- El script sondea hasta que el estado es ACTIVE
- Usar para archivos grandes que requieren procesamiento
- Puede tomar 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 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"
- Verifica las extensiones soportadas
- Convierte a un formato soportado 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 todavía en procesamiento" (sin --wait)
- El estado del archivo es PROCESSING, no ACTIVE
- Usa la bandera
--waito verifica el estado más tarde - Los archivos grandes (especialmente videos) toman tiempo
- El procesamiento puede tardar de minutos a horas
Mejores Prácticas
Estrategia de Subida
- Usa
--waitpara archivos que usarás de inmediato - Omite
--waitpara 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 nombres consistentes
- Incluye fechas o versiones en los nombres
- Agrupa archivos relacionados juntos
- Documenta los nombres de archivo en tu código
Consejos de Rendimiento
- Sube varios 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
- Verifica el estado después de la subida
- Reintenta subidas fallidas
- Verifica la integridad del archivo antes de subir
- Registra los nombres de archivo para auditorías
Integración con Otras Habilidades
- gemini-text: Análisis multimodal, procesamiento de documentos
- gemini-image: Generar imágenes basadas en referencia subida
- 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
- Eliminar archivos antiguos para liberar almacenamiento
- Los archivos pueden caducar después de un período determinado
- Descargar archivos importantes para respaldo
Habilidades Relacionadas
- gemini-text: Analizar archivos subidos con generación de texto
- gemini-image: Crear imágenes basadas en referencias subidas
- gemini-batch: Usar archivos subidos en procesamiento por lotes
- gemini-embeddings: Generar embeddings a partir del contenido del archivo
Referencia Rápida
# Subida básica
python scripts/upload.py imagen.jpg
# Con nombre personalizado
python scripts/upload.py documento.pdf --name "Mi Documento"
# Esperar procesamiento
python scripts/upload.py video.mp4 --wait
# Varios 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 un 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)