Codificar e Enviar Imagens em Base64
Nesta página
Por que Utilizar Base64?
Na lição anterior, aprendeu como enviar imagens através de um URL. No entanto, a maioria das imagens processadas em contextos empresariais não possui um URL: uma fatura que acabou de chegar por e-mail, uma captura de ecrã gerada por um teste automatizado ou uma fotografia tirada por um operador numa linha de produção. Publicar estes ficheiros num servidor acessível pela internet apenas para os analisar seria absurdo e, frequentemente, proibido.
É aqui que entra a codificação Base64. Esta transforma os dados binários de uma imagem numa cadeia de texto que pode incluir diretamente no seu pedido à API, sem necessidade de um URL externo ou de alojamento intermédio.
Quando Utilizar URL vs. Base64
| Critério | URL | Base64 |
|---|---|---|
| Imagens já alojadas | Ideal | Desnecessário |
| Imagens locais | Não adequado | Ideal |
| Imagens geradas dinamicamente | Não adequado | Ideal |
| Latência de rede | Depende do servidor | Nenhuma (incorporada) |
| Tamanho do pedido | Leve | Mais pesado (~33%) |
| Segurança/privacidade | URL público | Dados dentro do pedido |
A regra é simples: se a imagem estiver acessível através de um URL estável, utilize o URL. Caso contrário, utilize Base64.
Codificar uma Imagem para Base64
Não são necessárias dependências externas; o Python fornece o módulo base64 na sua biblioteca padrão:
import base64
def encode_image(file_path):
"""Codifica um ficheiro de imagem numa cadeia Base64."""
with open(file_path, "rb") as f:
return base64.standard_b64encode(f.read()).decode("utf-8")
# Codificar uma imagem local
image_b64 = encode_image("captures/screenshot.png")
print(f"Comprimento da cadeia Base64: {len(image_b64)} caracteres")
O modo "rb" ao abrir o ficheiro não é opcional: ler uma imagem em modo de texto provocará um erro de descodificação. Espere cadeias longas — a codificação aumenta o tamanho em cerca de 33% comparativamente ao ficheiro original, pelo que uma imagem de 1 MB produzirá aproximadamente 1,33 MB de texto.
Formato Data URI
A cadeia bruta não é suficiente: a API precisa de conhecer o formato da imagem. Deve, portanto, apresentá-la como um data URI, que prefixa os dados com o seu tipo MIME:
data:image/{format};base64,{base64_data}
Os quatro prefixos utilizáveis correspondem aos formatos suportados:
data:image/jpeg;base64,...data:image/png;base64,...data:image/gif;base64,...data:image/webp;base64,...
Anunciar um PNG como image/jpeg causará um erro de processamento; daí a função de deteção no exemplo seguinte.
Exemplo Completo
Eis a cadeia completa, desde a leitura do ficheiro local até à resposta do modelo:
import base64
import os
from mistralai.client import Mistral
def encode_image(chemin):
"""Codifica uma imagem local para Base64."""
with open(chemin, "rb") as f:
return base64.standard_b64encode(f.read()).decode("utf-8")
# Determinar o tipo MIME
def obtenir_mime(chemin):
"""Devolve o tipo MIME com base na extensão."""
extensions = {
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".png": "image/png",
".gif": "image/gif",
".webp": "image/webp"
}
ext = os.path.splitext(chemin)[1].lower()
return extensions.get(ext, "image/jpeg")
# Preparar a imagem
chemin_image = "documents/facture-2024.png"
image_b64 = encode_image(chemin_image)
mime_type = obtenir_mime(chemin_image)
data_uri = f"data:{mime_type};base64,{image_b64}"
# Chamar a API
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Extraia todas as informações desta fatura."},
{"type": "image_url", "image_url": data_uri}
]
}
]
)
print(response.choices[0].message.content)
Ponto essencial: o campo chama-se sempre image_url, mesmo quando contém um data URI. A estrutura da mensagem não muda minimamente em relação à Lição 4; apenas o valor difere.
Codificar Imagens de Outras Fontes
Um ficheiro no disco é apenas um caso entre muitos. Se a sua imagem já existir na memória, como um objeto Pillow resultante de uma captura ou de um passo de processamento, escrevê-la no disco apenas para a ler de imediato seria um desvio desnecessário — um buffer de memória funciona perfeitamente:
import base64
from io import BytesIO
from PIL import Image
def pil_to_base64(pil_image):
"""Converte uma imagem Pillow num data URI Base64."""
buffer = BytesIO()
pil_image.save(buffer, format="PNG")
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
return f"data:image/png;base64,{b64}"
# Exemplo com uma imagem Pillow
img = Image.open("capture.png")
data_uri = pil_to_base64(img)
A mesma lógica aplica-se a uma imagem recuperada via HTTP que não deseja armazenar, por exemplo, porque provém de um link de curta duração:
import base64
import requests
def url_to_base64(url):
"""Descarrega uma imagem e converte-a num data URI."""
response = requests.get(url, timeout=10)
response.raise_for_status()
content_type = response.headers.get("Content-Type", "image/jpeg")
b64 = base64.standard_b64encode(response.content).decode("utf-8")
return f"data:{content_type};base64,{b64}"
data_uri = url_to_base64("https://example.com/photo.jpg")
Otimizar o Tamanho Antes da Codificação
Uma fotografia de smartphone atual pesa entre 4 a 8 MB, o que se torna quase 10 MB uma vez codificada. A API redimensionará a imagem de qualquer forma, como viu na Lição 2: estaria a pagar pela transferência inutilmente. Redimensione sempre antes de codificar.
from PIL import Image
from io import BytesIO
import base64
def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
"""Redimensiona, comprime e codifica uma imagem."""
img = Image.open(chemin)
# Redimensionar se necessário
if max(img.size) > taille_max:
img.thumbnail((taille_max, taille_max))
# Converter para JPEG para reduzir o tamanho
buffer = BytesIO()
img.convert("RGB").save(buffer, format="JPEG", quality=qualite)
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
taille_ko = len(buffer.getvalue()) / 1024
print(f"Imagem codificada: {taille_ko:.0f} KB")
return f"data:image/jpeg;base64,{b64}"
data_uri = preparer_et_encoder("photo_haute_resolution.png")
Exibir o tamanho final não é apenas decorativo: mantenha-o durante os seus testes, pois indicar-lhe-á imediatamente se o seu pipeline está a enviar 80 KB ou 8 MB em cada chamada.
Limites a Conhecer
Três restrições acompanham o Base64. A imagem codificada soma-se ao corpo do pedido HTTP, pelo que, acima de 10 MB, arrisca timeouts. A codificação também carrega a imagem inteira na memória: para processamento em lote, trate as imagens uma a uma em vez de construir uma lista de mil cadeias codificadas. Finalmente, ao contrário dos URLs, as imagens Base64 são retransmitidas na íntegra em cada pedido — analisar a mesma fatura duas vezes significa enviá-la duas vezes.
Pontos-chave
- O Base64 é ideal para imagens locais ou geradas dinamicamente
- O formato data URI combina o tipo MIME e os dados:
data:image/png;base64,... - Redimensione e comprima as suas imagens antes da codificação para otimizar a latência
- O Base64 aumenta o tamanho em cerca de 33% — mantenha as suas imagens abaixo de 10 MB
- Utilize URL quando a imagem já estiver alojada, Base64 em todos os outros casos