Parâmetro detail: auto, low e high
Nesta página
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
detailcontrola a profundidade da análise da imagem auto(predefinido) deixa o modelo decidir — esta é a escolha recomendadalowé rápido e económico, adequado para tarefas de classificaçãohighé lento mas preciso, adequado para OCR e análise de pormenor- Adapte o nível de detalhe ao tipo de tarefa para otimizar custos