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

Parâmetro detail: auto, low e high

Aula 2 de 12 Atualizada a 30 de julho de 2026 Iniciante
Nesta página
  1. Controlar a precisão da análise
  2. Os três níveis de detalhe
  3. Comparar os níveis
  4. Sintaxe por API
  5. Estratégia de otimização
  6. Pontos-chave

Controlar a precisão da análise

Quando envia uma imagem para o Grok, pode controlar o nível de detalhe da análise através do parâmetro detail. Este parâmetro afeta diretamente a qualidade da resposta, o tempo de processamento e o consumo de tokens.

Compreender este parâmetro é crucial para otimizar custos e adequar a precisão a cada caso de uso.

Os três níveis de detalhe

A API da xAI oferece três valores para o parâmetro detail:

Auto (valor predefinido)

Quando não especifica o parâmetro detail, o modelo utiliza auto. Este avalia automaticamente o nível de detalhe necessário com base na imagem e no seu prompt.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg"
}

Este é o comportamento recomendado para a maioria dos casos de uso. O modelo adapta a sua estratégia de análise consoante a complexidade percebida da imagem e a questão colocada.

Low (rápido e económico)

O modo low realiza uma análise rápida da imagem utilizando menos tokens. Esta é a escolha ideal quando necessita de uma compreensão geral sem entrar em pormenores finos.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg",
  "detail": "low"
}

Casos de uso para low:

  • Classificar o conteúdo da imagem (paisagem, retrato, documento, etc.)
  • Identificar o sujeito principal de uma fotografia
  • Ordenar rapidamente um lote de imagens
  • Verificar se uma imagem corresponde a um critério simples

High (lento e detalhado)

O modo high força uma análise exaustiva da imagem. O modelo examina cada zona à resolução máxima, o que consome mais tokens, mas produz descrições muito mais precisas.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg",
  "detail": "high"
}

Casos de uso para high:

  • Ler texto fino numa imagem (OCR)
  • Analisar gráficos com legendas detalhadas
  • Detetar defeitos em fotografias de produtos
  • Examinar capturas de ecrã de interfaces complexas

Comparar os níveis

Parâmetro Velocidade Tokens Precisão
auto Variável Variável Adaptativa
low Rápida Menos tokens Geral
high Lenta Mais tokens Detalhada

Sintaxe por API

A colocação do parâmetro detail varia consoante a API utilizada.

Responses API (recomendada)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_image",
            "image_url": "https://exemple.com/photo.jpg",
            "detail": "high"
        },
        {
            "type": "input_text",
            "text": "Read all visible text in this image."
        }
    ]
)

Chat Completions API (legada)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://exemple.com/photo.jpg",
                    "detail": "high"
                }
            },
            {
                "type": "text",
                "text": "Read all visible text in this image."
            }
        ]
    }]
)

Note que, na Chat Completions, o detail está aninhado dentro do objeto image_url, enquanto na Responses API se encontra ao mesmo nível que o image_url.

Estratégia de otimização

Em produção, uma boa prática consiste em adaptar o nível de detalhe consoante o tipo de tarefa:

def analyser_image(image_url, tache):
    # Tarefas simples → low para poupar custos
    if tache in ["classifier", "trier", "identifier_sujet"]:
        detail = "low"
    # Tarefas complexas → high para precisão
    elif tache in ["ocr", "graphique", "defaut_produit"]:
        detail = "high"
    # Predefinição → deixar o modelo decidir
    else:
        detail = "auto"

    return client.responses.create(
        model="grok-4.5",
        input=[
            {"type": "input_image", "image_url": image_url, "detail": detail},
            {"type": "input_text", "text": f"Task: {tache}"}
        ]
    )

Esta abordagem permite reduzir significativamente os custos com tokens em tarefas simples, mantendo ao mesmo tempo a máxima precisão onde esta é necessária.

Pontos-chave

  • O parâmetro detail controla a profundidade da análise da imagem
  • auto (predefinido) deixa o modelo decidir — esta é a escolha recomendada
  • low é rápido e económico, adequado para tarefas de classificação
  • high é lento mas preciso, adequado para OCR e análise de pormenor
  • Adapte o nível de detalhe ao tipo de tarefa para otimizar custos