Formato do conteúdo: cadeia de caracteres simples e matriz de objetos
Nesta página
Dois formatos para o campo content
O campo content de cada mensagem aceita dois formatos diferentes na API de Completions de Chat da xAI. A escolha depende do que envia ao modelo: texto simples ou conteúdo multimodal (texto + imagens).
Formato de cadeia de caracteres: o caso mais comum
Para mensagens puramente textuais, o campo content é uma simples cadeia de caracteres:
{
"role": "user",
"content": "Explain how a transformer works."
}
Este é o formato que utilizará na vasta maioria dos casos. É simples, legível e suficiente para todas as interações textuais com o Grok.
Para a mensagem system, o formato de cadeia de caracteres é quase sempre utilizado:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Formato de matriz: conteúdo multimodal
Quando precisa de enviar imagens juntamente com texto, o campo content torna-se uma matriz de objetos tipados. Cada objeto possui um campo type que indica a sua natureza.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Tipos de objetos disponíveis
A matriz de conteúdo aceita dois tipos de objetos:
text: um bloco de texto com a propriedadetextimage_url: uma referência a uma imagem com a propriedadeimage_url
Pode combinar tantos objetos quantos forem necessários numa única mensagem. Por exemplo, para pedir ao modelo que compare duas imagens:
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two architecture diagrams."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
O parâmetro detail para imagens
Cada objeto image_url aceita um parâmetro opcional detail que controla a resolução da análise:
auto: o modelo escolhe automaticamente o nível de detalhe (valor predefinido)low: análise rápida e económica, suficiente para imagens simples (ícones, diagramas básicos)high: análise detalhada, recomendada para imagens complexas (documentos, fotografias, interfaces)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
A escolha do nível de detalhe impacta diretamente o número de tokens consumidos e, consequentemente, o custo do pedido.
Quando utilizar cada formato?
A regra é simples:
- Apenas texto → formato de cadeia de caracteres (mais simples, mais legível)
- Texto + imagens → formato de matriz (obrigatório para multimodal)
- Apenas imagens → formato de matriz com apenas objetos
image_url
Um formato de matriz com um único objeto text é funcionalmente equivalente ao formato de cadeia de caracteres, mas desnecessariamente verboso:
// Equivalente, mas desnecessariamente complexo
{"content": [{"type": "text", "text": "Hello"}]}
// Prefira esta forma
{"content": "Hello"}
Restrições técnicas para imagens
Antes de enviar imagens para a API da xAI, tenha em conta estes limites:
- Tamanho máximo: 20 MiB por imagem
- Formatos aceites: apenas JPG, JPEG, PNG (sem GIF, WebP ou SVG)
- Quantidade: sem limite no número de imagens por pedido
- Modelos compatíveis: apenas grok-4.5 e superiores
As imagens podem ser fornecidas através de um URL público ou codificadas em base64 dentro do próprio URL (formato data:image/jpeg;base64,...).
Pontos-chave
- O campo
contentaceita uma cadeia de caracteres simples (texto) ou uma matriz de objetos (multimodal) - O formato de matriz utiliza objetos com um campo
type:"text"ou"image_url" - O parâmetro
detail(auto,low,high) controla a resolução da análise para imagens - As imagens estão limitadas a 20 MiB em JPG/PNG e requerem grok-4.5 ou superior
- Utilize o formato de cadeia de caracteres quando enviar apenas texto — é mais legível e simples