Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Enviar uma imagem através de um URL

Aula 4 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O método mais simples
  2. Formato da mensagem
  3. Exemplo completo em Python
  4. Adicionar um prompt de sistema
  5. Requisitos do URL
  6. Imagens provenientes de armazenamento na nuvem
  7. Gestão de erros
  8. Pontos-chave

O método mais simples

O envio de uma imagem através de um URL é a forma mais direta de utilizar a API Vision: fornece o endereço de uma imagem publicamente acessível e o Mistral faz o download da mesma para análise. O seu pedido mantém-se leve — algumas centenas de bytes — uma vez que transporta apenas uma ligação.

Priorize este método quando as suas imagens já estiverem alojadas num CDN, numa armazenamento na nuvem ou num sítio web, ou quando trabalhar com imagens públicas da web. Uma equipa que já armazena visuais de produtos num CDN pode começar a analisá-los sem alterar a sua infraestrutura.

Formato da mensagem

Uma mensagem multimodal com um URL de imagem segue esta estrutura:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Your question about the image"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

O campo image_url aceita qualquer URL HTTP ou HTTPS que aponte para um ficheiro de imagem válido nos formatos JPEG, PNG, GIF ou WebP.

Exemplo completo em Python

Eis um script completo, pronto a executar, que analisa uma imagem pública da Wikimedia, assumindo que a sua chave de API está definida no ambiente:

from mistralai.client import Mistral
import os

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

# Public image to analyze
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Call the Vision API
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe precisely what you see in this image."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

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

Note que passamos a chave através de os.environ em vez de a codificar diretamente no código. Esta é a única abordagem aceitável assim que o script sai da sua máquina local.

Adicionar um prompt de sistema

A resposta acima será correta, mas genérica — «uma formiga preta num fundo desfocado». Uma mensagem de sistema altera a natureza da análise ao atribuir um papel ao modelo antes de este visualizar a imagem:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "You are an entomology expert. Analyze insect images with scientific precision, identifying the species, family, and visible morphological characteristics."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Identify this insect."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Com este enquadramento, a mesma imagem produz uma identificação taxonómica e uma descrição morfológica. O prompt de sistema orienta a forma como o modelo analisa a imagem — uma alavanca poderosa para obter respostas especializadas, ao custo de apenas algumas dezenas de tokens.

Requisitos do URL

A API deve poder transferir a imagem sem qualquer contexto da sua sessão. Isto implica quatro requisitos: o URL deve ser publicamente acessível (sem páginas protegidas por autenticação); deve apontar diretamente para o ficheiro, e não para uma página HTML que contenha a imagem; o formato deve ser suportado (JPEG, PNG, GIF onde apenas o primeiro quadro é lido, ou WebP); e o tamanho deve permanecer razoável, abaixo de 20 MB.

A confusão mais comum envolve ligações de partilha. Uma ligação do Google Drive ou do Dropbox «partilhada com todos» devolve uma página HTML, e não um ficheiro de imagem: a chamada falha ou o modelo descreve uma interface web. A melhor prática é verificar o Content-Type antes do envio:

import requests

def verify_image_url(url):
    """Verify that a URL points to an accessible image."""
    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"Image accessible: {content_type}, {size / 1024:.0f} KB")
            return True
        else:
            print(f"Issue: status={response.status_code}, type={content_type}")
            return False
    except requests.RequestException as e:
        print(f"Connection error: {e}")
        return False

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

Um pedido HEAD é suficiente: recupera os cabeçalhos sem transferir o ficheiro.

Imagens provenientes de armazenamento na nuvem

Este requisito de acessibilidade pública parece incompatível com documentos confidenciais. A solução reside nos URLs pré-assinados: se as suas imagens estiverem num bucket S3, no Google Cloud Storage ou no Azure Blob, gera um endereço temporário que concede acesso a um único objeto durante um período que você especifica.

import boto3

s3 = boto3.client("s3")

# Generate a pre-signed URL valid for 1 hour
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Use this URL with the Vision API
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the total amount from this invoice."},
                {"type": "image_url", "image_url": presigned_url}
            ]
        }
    ]
)

O seu bucket permanece privado, o URL expira após o atraso especificado e você mantém a natureza leve do pedido. Defina ExpiresIn pelo período mais curto possível: alguns minutos são mais do que suficientes para uma chamada à API.

Gestão de erros

Uma chamada que depende de uma transferência remota pode falhar por razões fora do seu controlo — a imagem foi apagada, o URL expirou ou o servidor de alojamento está indisponível. Em produção, nunca deixe a exceção bruta propagar-se até ao utilizador:

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 this image."},
                    {"type": "image_url", "image_url": "https://example.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")

Teste a sua gestão de erros com um URL deliberadamente inválido antes de implementar: este é o cenário mais frequente e aquele que é menos frequentemente testado.

Pontos-chave

  • O envio via URL é o método mais simples — basta um URL público
  • O campo content da mensagem é um array contendo elementos text e image_url
  • O URL deve apontar diretamente para um ficheiro de imagem acessível
  • Os URLs pré-assinados permitem utilizar imagens privadas de forma segura
  • Adicione sempre um prompt de sistema para orientar a análise do modelo