API de Gemini File

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 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.js

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

Cuándo usarlo:

Para subir cualquier archivo para procesamiento con 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 (obligatorio)	`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 de trabajo 1: Subida básica de archivo

node scripts/upload.js image.jpg

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

Flujo de trabajo 2: Subida con nombre personalizado

node scripts/upload.js document.pdf --name "Informe Trimestral Q4 2026"

Ideal para: Organizar archivos, hacer seguimiento de subidas
Úsalo cuando: El nombre original del archivo no es lo suficientemente descriptivo
El nombre mostrado aparece en los listados de archivos

Flujo de trabajo 3: Subida y espera de procesamiento

node scripts/upload.js video.mp4 --wait

Ideal para: Archivos grandes, videos, audio
Espera a que el archivo esté en 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
node scripts/upload.js photo.png --name "foto-producto"

# 2. Usar con gemini-text para análisis
node skills/gemini-text/scripts/generate.js "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
node scripts/upload.js articulo-investigacion.pdf --name "Articulo-IA" --wait

# 2. Extraer contenido con gemini-text
node skills/gemini-text/scripts/generate.js "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 lotes

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

# 2. Crear un 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 de trabajo 7: Subir audio para transcripción

# 1. Subir audio
node scripts/upload.js entrevista.mp3 --name "entrevista-001" --wait

# 2. Procesar con gemini-text (si está disponible la transcripción)
node skills/gemini-text/scripts/generate.js "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)
node scripts/upload.js demo-producto.mp4 --name "video-demo" --wait

# 2. Analizar con gemini-text
node skills/gemini-text/scripts/generate.js "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 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 a la API
URI: Referencia interna de Google Cloud Storage
Estado: PROCESSING = esperar, ACTIVE = listo

Con la opción --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 requieran procesamiento
Puede tardar minutos para videos

Usar archivos subidos

Una vez subidos, referencia el archivo por nombre:

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

Problemas comunes

«google-genai no instalado»

npm install @google/genai@latest dotenv@latest

«Archivo no encontrado»

Verifica que la ruta del archivo sea correcta
Usa rutas absolutas si las relativas fallan
Comprueba que la extensión coincida con 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é dañado
Intenta volver a subir el archivo
Confirma que el formato del archivo sea válido
Revisa los límites de la cuota de la API

«El archivo todavía se está procesando» (sin --wait)

El estado del archivo es PROCESSING, no ACTIVE
Usa la opción --wait o verifica el estado más tarde
Los archivos grandes (especialmente videos) requieren tiempo
El procesamiento puede tardar 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 descriptivos con --name para organización
Lleva un registro de los nombres de archivo para usarlos después

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 varios 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
Confirma la integridad del archivo antes de subirlo
Registra los nombres de archivo para pistas de auditoría

Integración con otras habilidades

gemini-text: Análisis multimodal, procesamiento de documentos
gemini-image: Generar imágenes basadas en una referencia subida
gemini-batch: Usar archivos subidos en trabajos por lotes
gemini-embeddings: Crear incrustaciones a partir del contenido de archivos

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 determinado
Descarga archivos importantes como respaldo

Habilidades relacionadas

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 incrustaciones a partir del contenido de archivos

Referencia rápida

# Subida básica
node scripts/upload.js image.jpg

# Con nombre personalizado
node scripts/upload.js document.pdf --name "Mi Documento"

# Esperar procesamiento
node scripts/upload.js video.mp4 --wait

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

API de gestión de archivos

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Listar todos los archivos
for await (const file of client.files.list()) {
  console.log(`${file.name}: ${file.displayName} (${file.state})`);
}

// Obtener información de un archivo
const file = await client.files.get({ name: "files/abc123..." });
console.log(`Estado: ${file.state}`);

// Eliminar archivo
await 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)

Preguntar en tu IA favorita

Documentación