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

Formato do conteúdo: cadeia de caracteres simples e matriz de objetos

Aula 3 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Dois formatos para o campo content
  2. Formato de cadeia de caracteres: o caso mais comum
  3. Formato de matriz: conteúdo multimodal
  4. Quando utilizar cada formato?
  5. Restrições técnicas para imagens
  6. Pontos-chave

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 propriedade text
  • image_url: uma referência a uma imagem com a propriedade image_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 content aceita 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