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

Visão: Analisar Imagens com o Grok

Aula 7 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Compreensão de Imagens com Chat Completions
  2. Enviar uma Imagem via URL
  3. Enviar uma Imagem em Base64
  4. Níveis de Detalhe: auto, low e high
  5. Analisar Múltiplas Imagens
  6. Restrições Técnicas
  7. Pontos-chave

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 content com objetos image_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) e high (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