Formatos de Imagem: URL e Base64
Nesta página
Atualizado em 3 de novembro de 2026. Com a Responses API, os objetos
input_imageeinput_textdevem ser inseridos nocontentde uma mensagem{"role": "user", ...}, e não diretamente eminput. O exemplo em Python anterior chamavaclient.responses.create()no clientexai-sdk, método que este não possui, e escrevia a chave da API diretamente no código: agora utilizauser(...)eimage(...)do SDK, com a chave lida a partir do ambiente. Foi adicionado o aviso da xAI sobre o armazenamento do histórico. Código verificado comxai-sdk1.21.0. Fonte: Image Understanding.
Envio de Imagens para o Grok
Os modelos Grok, a partir da versão grok-4.5, incluem capacidades de visão. Pode enviar uma ou mais imagens nos seus pedidos à API, e o modelo analisá-las-á para responder às suas perguntas. A isto chama-se compreensão de imagem ou visão multimodal.
Antes de explorar casos de uso, é essencial dominar os dois formatos de submissão de imagens suportados pela API da xAI.
URL Direta
O método mais simples consiste em fornecer o URL público de uma imagem. O modelo fará o download e a analisará automaticamente.
Com a Responses API (endpoint principal):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Describe this image in detail."
}
]
}
]
}
A xAI recomenda que, ao enviar imagens, não armazene o histórico de pedidos e respostas nos seus servidores, caso contrário o pedido poderá falhar: com a Responses API, passe "store": false.
Com a Chat Completions API (legado, compatível com OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Describe this image in detail."
}
]
}
]
}
O URL deve apontar para um ficheiro de imagem acessível publicamente. Se a imagem estiver protegida por autenticação ou num CDN privado, utilize o formato Base64.
Codificado em Base64 (Data URI)
O segundo formato envolve a codificação da imagem diretamente no pedido como uma cadeia Base64, precedida por um prefixo MIME. Este é o método ideal quando trabalha com imagens locais, capturas de ecrã ou ficheiros gerados dinamicamente.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
O prefixo data:image/jpeg;base64, informa o modelo sobre o tipo MIME da imagem. Ajuste-o conforme o formato:
data:image/jpeg;base64,para ficheiros JPG/JPEGdata:image/png;base64,para ficheiros PNG
Codificar uma Imagem em Python
import base64
with open("photo.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
image_url = f"data:image/jpeg;base64,{image_data}"
Codificar em JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Principais Diferenças entre URL e Base64
| Critério | URL | Base64 |
|---|---|---|
| Tamanho do pedido | Leve (apenas o URL) | Pesado (+33% face ao ficheiro original) |
| Acessibilidade | Requer imagem pública | Funciona com qualquer ficheiro local |
| Latência | Download pelo servidor | Dados diretamente no pedido |
| Caso de uso típico | Imagens web, CDN, armazenamento na nuvem | Ficheiros locais, capturas de ecrã, uploads |
Misturar Texto e Imagens
O content de uma mensagem aceita um array misto de objetos input_image e input_text, em qualquer ordem: pode alternar livremente entre texto e imagens. Com o SDK nativo da xAI, a mesma mensagem é construída com user(), que aceita texto e imagens criadas por image() em sequência:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # chave lida de XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Compare these two photos:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"What are the main differences?",
)
)
response = chat.sample()
print(response.content)
A função image() aceita um URL público ou um Data URI em Base64.
Pontos-chave
- São suportados dois formatos de imagem: URL Direto e Base64 (Data URI)
- Os formatos aceites são apenas JPG, JPEG e PNG
- Cada imagem não deve exceder 20 MiB
- O número de imagens por pedido é ilimitado
- A Responses API coloca
input_imagenocontentde uma mensagem; a Chat Completions usa partesimage_url; o SDK da xAI usaimage()dentro deuser() - Prefira o URL para imagens públicas e o Base64 para ficheiros locais