Explora las capacidades de visión con la API de Gemini

Ver en ai.google.dev Prueba un notebook de Colab Ver notebook en GitHub

Los modelos de Gemini pueden procesar imágenes y videos, lo que permite muchos casos de uso pioneros para desarrolladores que, históricamente, habrían requerido modelos específicos de dominio. Estas son algunas de las capacidades de visión de Gemini:

  • Agrega leyendas y responde preguntas sobre imágenes
  • Transcribe y razona sobre archivos PDF, incluidos hasta 2 millones de tokens
  • Describir, segmentar y extraer información de videos de hasta 90 minutos de duración
  • Detecta objetos en una imagen y muestra las coordenadas del cuadro delimitador

Gemini se creó para ser multimodal desde cero y seguimos ampliando los límites de lo posible.

Entrada de imágenes

Para un tamaño total de la carga útil de la imagen inferior a 20 MB, te recomendamos que subas imágenes codificadas en base64 o que subas directamente archivos de imagen almacenados de forma local.

Cómo trabajar con imágenes locales

Si usas la biblioteca de imágenes de Python (Pillow ), también puedes usar los objetos de imagen de PIL.

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

Imágenes codificadas en Base64

Para subir URLs de imágenes públicas, debes codificarlas como cargas útiles de Base64. En el siguiente ejemplo de código, se muestra cómo hacerlo con solo herramientas de bibliotecas estándar:

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

Varias imágenes

Para mostrar una instrucción con varias imágenes, puedes proporcionar varias imágenes en la llamada a generate_content. Pueden estar en cualquier formato compatible, incluido base64 o PIL.

from google import genai
from google.genai import types

import pathlib
import PIL.Image

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

Ten en cuenta que estas llamadas a datos intercalados no incluyen muchas de las funciones disponibles a través de la API de File, como obtener metadatos de archivos, crear una lista o borrar archivos.

Cargas útiles de imágenes grandes

Cuando la combinación de archivos y las instrucciones del sistema que deseas enviar sea superior a 20 MB, usa la API de File para subirlos.

Usa el método media.upload de la API de File para subir una imagen de cualquier tamaño.

Después de subir el archivo, puedes realizar solicitudes GenerateContent que hagan referencia al URI de la API de File. Selecciona el modelo generativo y proporciónale una instrucción de texto y la imagen subida.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

Compatibilidad con OpenAI

Puedes acceder a las capacidades de comprensión de imágenes de Gemini con las bibliotecas de OpenAI. Esto te permite integrar Gemini en los flujos de trabajo existentes de OpenAI actualizando tres líneas de código y usando tu clave de API de Gemini. Consulta el ejemplo de comprensión de imágenes para ver el código que muestra cómo enviar imágenes codificadas como cargas útiles de Base64.

Instrucciones con imágenes

En este instructivo, subirás imágenes con la API de File o como datos intercalados, y generarás contenido basado en esas imágenes.

Detalles técnicos (imágenes)

Gemini 1.5 Pro y 1.5 Flash admiten un máximo de 3,600 archivos de imagen.

Las imágenes deben estar en uno de los siguientes tipos MIME de datos de imágenes:

  • PNG - image/png
  • JPEG - image/jpeg
  • WEBP: image/webp
  • HEIC: image/heic
  • HEIF: image/heif

Tokens

A continuación, te mostramos cómo se calculan los tokens para las imágenes:

  • Gemini 1.0 Pro Vision: Cada imagen representa 258 tokens.
  • Gemini 1.5 Flash y Gemini 1.5 Pro: Si ambas dimensiones de una imagen son menores o iguales que 384 píxeles, se usan 258 tokens. Si una dimensión de una imagen es superior a 384 píxeles, la imagen se corta en mosaicos. El tamaño de cada mosaico se establece de forma predeterminada en la dimensión más pequeña (ancho o alto) dividida por 1.5. Si es necesario, cada mosaico se ajusta para que no sea inferior a 256 píxeles ni mayor que 768 píxeles. Luego, cada tarjeta cambia de tamaño a 768 × 768 y usa 258 tokens.
  • Gemini 2.0 Flash: Las entradas de imagen con ambas dimensiones <=384 píxeles se cuentan como 258 tokens. Las imágenes más grandes en una o ambas dimensiones se recortan y se escalan según sea necesario en tarjetas de 768 × 768 píxeles, cada una de las cuales se cuenta como 258 tokens.

Para obtener los mejores resultados

  • Rota las imágenes a la orientación correcta antes de subirlas.
  • Evita las imágenes borrosas.
  • Si usas una sola imagen, coloca la instrucción de texto después de la imagen.

Funciones

En esta sección, se describen las capacidades de visión específicas del modelo Gemini, como la detección de objetos y las coordenadas del cuadro de límite.

Obtén un cuadro de límite para un objeto

Los modelos de Gemini se entrenan para mostrar coordenadas de cuadros de límite como anchos o alturas relativos en el rango de [0, 1]. Luego, estos valores se ajustan a 1,000 y se convierten en números enteros. En realidad, las coordenadas representan el cuadro de límite en una versión de la imagen de 1,000 x 1,000 píxeles. Por lo tanto, deberás volver a convertir estas coordenadas en las dimensiones de tu imagen original para asignar con precisión los cuadros de límite.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

prompt = (
  "Return a bounding box for each of the objects in this image "
  "in [ymin, xmin, ymax, xmax] format.")

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

Puedes usar cuadros de límite para la detección y localización de objetos en imágenes y videos. Si identificas y delimitas con precisión los objetos con cuadros de límites, puedes desbloquear una amplia variedad de aplicaciones y mejorar la inteligencia de tus proyectos.

Beneficios clave

  • Fácil: Integra funciones de detección de objetos en tus aplicaciones con facilidad, independientemente de tu experiencia en visión artificial.
  • Personalizable: Produce cuadros de límite según instrucciones personalizadas (p.ej., "Quiero ver los cuadros de límite de todos los objetos verdes en esta imagen"), sin tener que entrenar un modelo personalizado.

Detalles técnicos

  • Entrada: Tu instrucción y las imágenes o los fotogramas de video asociados.
  • Resultado: Rectángulos de límite en formato [y_min, x_min, y_max, x_max]. La esquina superior izquierda es el origen. Los ejes x y y se orientan horizontal y verticalmente, respectivamente. Los valores de las coordenadas se normalizan de 0 a 1,000 para cada imagen.
  • Visualización: Los usuarios de AI Studio verán los cuadros de límite trazados dentro de la IU.

Para desarrolladores de Python, prueba el notebook de comprensión espacial 2D o el notebook experimental de puntero 3D.

Cómo normalizar coordenadas

El modelo muestra las coordenadas del cuadro delimitador en el formato [y_min, x_min, y_max, x_max]. Para convertir estas coordenadas normalizadas en las coordenadas de píxeles de tu imagen original, sigue estos pasos:

  1. Divide cada coordenada de salida por 1,000.
  2. Multiplica las coordenadas x por el ancho de la imagen original.
  3. Multiplica las coordenadas y por la altura de la imagen original.

Para explorar ejemplos más detallados de cómo generar coordenadas de cuadro delimitador y visualizarlas en imágenes, te recomendamos que revises nuestro ejemplo de libro de recetas de detección de objetos.

Sugerencias con video

En este instructivo, subirás un video con la API de File y generarás contenido según esas imágenes.

Detalles técnicos (video)

Gemini 1.5 Pro y Flash admiten hasta aproximadamente una hora de datos de video.

El video debe estar en uno de los siguientes tipos de MIME de formato de video:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

El servicio de la API de File extrae fotogramas de imágenes de videos a 1 fotograma por segundo (FPS) y audio a 1 Kbps, en un solo canal, y agrega marcas de tiempo cada segundo. Estas tarifas están sujetas a cambios en el futuro para mejorar la inferencia.

Los fotogramas individuales son 258 tokens y el audio es de 32 tokens por segundo. Con los metadatos, cada segundo de video se convierte en alrededor de 300 tokens, lo que significa que una ventana de contexto de 1 millón puede contener un poco menos de una hora de video.

Para hacer preguntas sobre ubicaciones con marcas de tiempo, usa el formato MM:SS, en el que los dos primeros dígitos representan minutos y los dos últimos segundos.

Para lograr resultados óptimos, haz lo siguiente:

  • Usa un video por instrucción.
  • Si usas un solo video, coloca la instrucción de texto después del video.

Sube un archivo de video con la API de File

La API de File acepta formatos de archivo de video directamente. En este ejemplo, se usa el cortometraje de la NASA “Jupiter's Great Red Spot Shrinks and Grows”. Crédito: Centro de vuelo espacial Goddard (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" es de dominio público y no muestra a personas identificables. (Lineamientos de uso de imágenes y contenido multimedia de la NASA.)

Comienza por recuperar el video corto:

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

Sube el video con la API de File y, luego, imprime el URI.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
print(f"Completed upload: {video_file.uri}")

Verifica la carga de archivos y comprueba el estado

Llama al método files.get para verificar que la API haya recibido los archivos correctamente.

import time

# Check whether the file is ready to be used.
while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(1)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

print('Done')

Instrucción con un video y texto

Una vez que el video subido esté en el estado ACTIVE, podrás realizar solicitudes GenerateContent que especifiquen el URI de la API de File para ese video. Selecciona el modelo generativo y proporciónale el video subido y una instrucción de texto.

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

# Print the response, rendering any Markdown
Markdown(response.text)

Consulta las marcas de tiempo en el contenido

Puedes usar marcas de tiempo del formato HH:MM:SS para hacer referencia a momentos específicos del video.

prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Transcribe videos y proporciona descripciones visuales

Los modelos de Gemini pueden transcribir y proporcionar descripciones visuales del contenido de video mediante el procesamiento de la pista de audio y los fotogramas visuales. En el caso de las descripciones visuales, el modelo toma muestras del video a una velocidad de 1 fotograma por segundo. Esta tasa de muestreo puede afectar el nivel de detalle de las descripciones, en especial en el caso de los videos con imágenes que cambian rápidamente.

prompt = (
    "Transcribe the audio from this video, giving timestamps for "
    "salient events in the video. Also provide visual descriptions.")

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Enumerar archivos

Puedes enumerar todos los archivos subidos con la API de archivos y sus URIs con files.list.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

Borrar archivos

Los archivos subidos con la API de Files se borran automáticamente después de 2 días. También puedes borrarlos de forma manual con files.delete.

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

¿Qué sigue?

En esta guía, se muestra cómo subir archivos de imagen y video con la API de File y, luego, generar resultados de texto a partir de entradas de imagen y video. Para obtener más información, consulta los siguientes recursos:

  • Estrategias de indicaciones de archivos: La API de Gemini admite indicaciones con datos de texto, imagen, audio y video, también conocidos como indicaciones multimodales.
  • Instrucciones del sistema: Las instrucciones del sistema te permiten dirigir el comportamiento del modelo según tus necesidades y casos de uso específicos.
  • Orientación de seguridad: A veces, los modelos de IA generativa producen resultados inesperados, como resultados imprecisos, sesgados o ofensivos. El procesamiento posterior y la evaluación humana son esenciales para limitar el riesgo de daños que pueden causar estos resultados.