Visão: Analisar Imagens com o Grok
Nesta página
Compreensão de Imagens com Chat Completions
Os modelos Grok (a partir do grok-4.5) incluem capacidades de visão que lhe permitem analisar, descrever e raciocinar sobre imagens. Utiliza esta funcionalidade através do formato de array do campo content, combinando objetos text e image_url.
Os casos de uso são numerosos: extração de texto de documentos digitalizados (OCR), análise de gráficos, descrição de interfaces de utilizador, comparação visual ou interpretação de diagramas técnicos.
Enviar uma Imagem via URL
A forma mais simples consiste em fornecer o URL público da imagem:
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe what you see in this image."},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo-architecture.jpg",
"detail": "high"
}
}
]
}
]
)
print(response.choices[0].message.content)
Os servidores da xAI transferem a imagem no momento do pedido. Esta deve estar acessível publicamente.
Enviar uma Imagem em Base64
Para imagens locais ou privadas, utilize a codificação base64:
import base64
def encode_image(image_path: str) -> str:
with open(image_path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
image_data = encode_image("capture-ecran.png")
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What text is visible in this screenshot?"},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{image_data}"
}
}
]
}
]
)
O formato do URL é data:image/{format};base64,{data}, onde {format} é jpeg, jpg ou png.
Níveis de Detalhe: auto, low e high
O parâmetro detail controla a resolução à qual o modelo analisa a imagem:
detail: “low”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/icone.png",
"detail": "low"
}
}
A imagem é reduzida para uma baixa resolução antes da análise. Este é o modo mais rápido e o que consome menos tokens. Utilize-o para imagens simples: ícones, logótipos, diagramas básicos.
detail: “high”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
A imagem é analisada em alta resolução. O modelo consegue ler texto pequeno, identificar detalhes finos e analisar áreas específicas. Este é o modo recomendado para documentos, capturas de ecrã e fotografias detalhadas.
detail: “auto”
O modelo escolhe automaticamente o nível de detalhe com base no tamanho e na complexidade da imagem. Este é o valor predefinido se omitir o parâmetro.
Analisar Múltiplas Imagens
Pode enviar várias imagens numa única mensagem para tarefas de comparação ou análise cruzada:
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two versions of the design. What are the differences?"},
{"type": "image_url", "image_url": {"url": "https://example.com/v1.png", "detail": "high"}},
{"type": "image_url", "image_url": {"url": "https://example.com/v2.png", "detail": "high"}}
]
}
]
)
Não existe um limite para o número de imagens por pedido, mas cada imagem consome tokens adicionais.
Restrições Técnicas
Tenha em conta estes limites ao utilizar a visão:
- Tamanho máximo: 20 MiB por imagem
- Formatos suportados: Apenas JPG, JPEG e PNG
- Modelos compatíveis: grok-4 e superiores (modelos mais antigos não suportam visão)
- Tokens: as imagens consomem tokens que se somam ao custo do texto do pedido
Pontos-chave
- A visão utiliza o formato de array do campo
contentcom objetosimage_url - As imagens podem ser enviadas via URL público ou codificadas em base64
- Três níveis de detalhe:
auto(predefinido),low(rápido/económico) ehigh(detalhado) - Tamanho máximo de 20 MiB por imagem, apenas formatos JPG e PNG
- É possível enviar múltiplas imagens numa única mensagem para comparações