Ir al contenido principal
Español— Elegir un idioma
Menú

Enviar una imagen mediante URL

Lección 4 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. El método más sencillo
  2. Formato del mensaje
  3. Ejemplo completo en Python
  4. Añadir un prompt de sistema
  5. Requisitos de la URL
  6. Imágenes desde almacenamiento en la nube
  7. Gestión de errores
  8. Puntos clave

El método más sencillo

Enviar una imagen mediante URL es la forma más directa de utilizar la API de Visión: proporcionas la dirección de una imagen accesible públicamente y Mistral la descarga para analizarla. Tu solicitud se mantiene ligera, apenas unos cientos de bytes, ya que solo transporta un enlace.

Prioriza este método cuando tus imágenes ya estén alojadas en una CDN, en un almacenamiento en la nube o en un sitio web, o cuando trabajes con imágenes públicas de la web. Un equipo que ya almacena visuales de producto en una CDN puede empezar a analizarlos sin modificar su infraestructura.

Formato del mensaje

Un mensaje multimodal con una URL de imagen sigue esta estructura:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Tu pregunta sobre la imagen"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

El campo image_url acepta cualquier URL HTTP o HTTPS que apunte a un archivo de imagen válido en formato JPEG, PNG, GIF o WebP.

Ejemplo completo en Python

Aquí tienes un script completo y listo para ejecutar que analiza una imagen pública de Wikimedia, asumiendo que tu clave de API está definida en el entorno:

from mistralai.client import Mistral
import os

# Inicializar el cliente
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Imagen pública a analizar
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Llamar a la API de Visión
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe con precisión lo que ves en esta imagen."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

Ten en cuenta que pasamos la clave mediante os.environ en lugar de codificarla directamente. Este es el único enfoque aceptable una vez que el script sale de tu máquina local.

Añadir un prompt de sistema

La respuesta anterior será correcta pero genérica: «una hormiga negra sobre un fondo borroso». Un mensaje de sistema cambia la naturaleza del análisis al asignar un rol al modelo antes de que este vea la imagen:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "Eres un experto en entomología. Analiza imágenes de insectos con precisión científica, identificando la especie, la familia y las características morfológicas visibles."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Identifica este insecto."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Con este encuadre, la misma imagen produce una identificación taxonómica y una descripción morfológica. El prompt de sistema guía cómo el modelo analiza la imagen; es una palanca potente para obtener respuestas especializadas a costa de apenas unas pocas decenas de tokens.

Requisitos de la URL

La API debe poder descargar la imagen sin ningún contexto de tu sesión. Esto implica cuatro requisitos: la URL debe ser accesible públicamente (sin páginas tras autenticación); debe apuntar directamente al archivo, no a una página HTML que contenga la imagen; el formato debe ser compatible (JPEG, PNG, GIF donde solo se lee el primer fotograma, o WebP); y el tamaño debe mantenerse razonable, por debajo de 20 MB.

La confusión más habitual surge con los enlaces para compartir. Un enlace de Google Drive o Dropbox «compartido con todos» devuelve una página HTML, no un archivo de imagen: la llamada falla o el modelo describe una interfaz web. La mejor práctica es verificar el Content-Type antes de enviar:

import requests

def verify_image_url(url):
    """Verifica que una URL apunte a una imagen accesible."""
    try:
        response = requests.head(url, timeout=5, allow_redirects=True)
        content_type = response.headers.get("Content-Type", "")

        if response.status_code == 200 and "image" in content_type:
            size = int(response.headers.get("Content-Length", 0))
            print(f"Imagen accesible: {content_type}, {size / 1024:.0f} KB")
            return True
        else:
            print(f"Problema: estado={response.status_code}, tipo={content_type}")
            return False
    except requests.RequestException as e:
        print(f"Error de conexión: {e}")
        return False

verify_image_url("https://example.com/photo.jpg")

Una solicitud HEAD es suficiente: recupera las cabeceras sin descargar el archivo.

Imágenes desde almacenamiento en la nube

Este requisito de accesibilidad pública parece incompatible con documentos confidenciales. La solución reside en las URL prefirmadas: si tus imágenes están en un bucket de S3, en Google Cloud Storage o en Azure Blob, generas una dirección temporal que concede acceso a un único objeto durante un periodo que tú especificas.

import boto3

s3 = boto3.client("s3")

# Generar una URL prefirmada válida durante 1 hora
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Usar esta URL con la API de Visión
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extrae el importe total de esta factura."},
                {"type": "image_url", "image_url": presigned_url}
            ]
        }
    ]
)

Tu bucket permanece privado, la URL caduca tras el retraso especificado y conservas la naturaleza ligera de la solicitud. Configura ExpiresIn lo más corto posible: unos pocos minutos son más que suficientes para una llamada a la API.

Gestión de errores

Una llamada que depende de una descarga remota puede fallar por razones fuera de tu control: la imagen se ha eliminado, la URL ha caducado o el servidor de alojamiento no está disponible. En producción, nunca dejes que la excepción cruda llegue hasta el usuario:

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Describe esta imagen."},
                    {"type": "image_url", "image_url": "https://example.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")

Prueba tu gestión de errores con una URL deliberadamente inválida antes de desplegar: este es el escenario más frecuente y el que menos se suele probar.

Puntos clave

  • El envío mediante URL es el método más sencillo; solo necesitas una URL pública
  • El campo content del mensaje es un array que contiene elementos text e image_url
  • La URL debe apuntar directamente a un archivo de imagen accesible
  • Las URL prefirmadas permiten usar imágenes privadas de forma segura
  • Añade siempre un prompt de sistema para guiar el análisis del modelo