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

Formatos de Imagem: URL e Base64

Aula 1 de 12 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Envio de Imagens para o Grok
  2. URL Direta
  3. Codificado em Base64 (Data URI)
  4. Principais Diferenças entre URL e Base64
  5. Misturar Texto e Imagens
  6. Pontos-chave

Atualizado em 3 de novembro de 2026. Com a Responses API, os objetos input_image e input_text devem ser inseridos no content de uma mensagem {"role": "user", ...}, e não diretamente em input. O exemplo em Python anterior chamava client.responses.create() no cliente xai-sdk, método que este não possui, e escrevia a chave da API diretamente no código: agora utiliza user(...) e image(...) do SDK, com a chave lida a partir do ambiente. Foi adicionado o aviso da xAI sobre o armazenamento do histórico. Código verificado com xai-sdk 1.21.0. Fonte: Image Understanding.

Envio de Imagens para o Grok

Grok a analisar uma imagem Os modelos Grok, a partir da versão grok-4.5, incluem capacidades de visão. Pode enviar uma ou mais imagens nos seus pedidos à API, e o modelo analisá-las-á para responder às suas perguntas. A isto chama-se compreensão de imagem ou visão multimodal.

Antes de explorar casos de uso, é essencial dominar os dois formatos de submissão de imagens suportados pela API da xAI.

2
Formatos suportados
20 MiB
Tamanho máximo por imagem
JPG/PNG
Formatos aceites
Ilimitado
Número de imagens

URL Direta

O método mais simples consiste em fornecer o URL público de uma imagem. O modelo fará o download e a analisará automaticamente.

Com a Responses API (endpoint principal):

{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_image",
          "image_url": "https://exemple.com/photo-produit.jpg"
        },
        {
          "type": "input_text",
          "text": "Describe this image in detail."
        }
      ]
    }
  ]
}

A xAI recomenda que, ao enviar imagens, não armazene o histórico de pedidos e respostas nos seus servidores, caso contrário o pedido poderá falhar: com a Responses API, passe "store": false.

Com a Chat Completions API (legado, compatível com OpenAI):

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo-produit.jpg"
          }
        },
        {
          "type": "text",
          "text": "Describe this image in detail."
        }
      ]
    }
  ]
}

O URL deve apontar para um ficheiro de imagem acessível publicamente. Se a imagem estiver protegida por autenticação ou num CDN privado, utilize o formato Base64.

Codificado em Base64 (Data URI)

O segundo formato envolve a codificação da imagem diretamente no pedido como uma cadeia Base64, precedida por um prefixo MIME. Este é o método ideal quando trabalha com imagens locais, capturas de ecrã ou ficheiros gerados dinamicamente.

{
  "type": "input_image",
  "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

O prefixo data:image/jpeg;base64, informa o modelo sobre o tipo MIME da imagem. Ajuste-o conforme o formato:

  • data:image/jpeg;base64, para ficheiros JPG/JPEG
  • data:image/png;base64, para ficheiros PNG

Codificar uma Imagem em Python

import base64

with open("photo.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

image_url = f"data:image/jpeg;base64,{image_data}"

Codificar em JavaScript/Node.js

import { readFileSync } from 'fs';

const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;

Principais Diferenças entre URL e Base64

Critério URL Base64
Tamanho do pedido Leve (apenas o URL) Pesado (+33% face ao ficheiro original)
Acessibilidade Requer imagem pública Funciona com qualquer ficheiro local
Latência Download pelo servidor Dados diretamente no pedido
Caso de uso típico Imagens web, CDN, armazenamento na nuvem Ficheiros locais, capturas de ecrã, uploads

Misturar Texto e Imagens

O content de uma mensagem aceita um array misto de objetos input_image e input_text, em qualquer ordem: pode alternar livremente entre texto e imagens. Com o SDK nativo da xAI, a mesma mensagem é construída com user(), que aceita texto e imagens criadas por image() em sequência:

from xai_sdk import Client
from xai_sdk.chat import image, user

client = Client()  # chave lida de XAI_API_KEY

chat = client.chat.create(model="grok-4.5")
chat.append(
    user(
        "Compare these two photos:",
        image(image_url="https://exemple.com/photo1.jpg", detail="high"),
        image(image_url="https://exemple.com/photo2.jpg", detail="high"),
        "What are the main differences?",
    )
)

response = chat.sample()
print(response.content)

A função image() aceita um URL público ou um Data URI em Base64.

Pontos-chave

  • São suportados dois formatos de imagem: URL Direto e Base64 (Data URI)
  • Os formatos aceites são apenas JPG, JPEG e PNG
  • Cada imagem não deve exceder 20 MiB
  • O número de imagens por pedido é ilimitado
  • A Responses API coloca input_image no content de uma mensagem; a Chat Completions usa partes image_url; o SDK da xAI usa image() dentro de user()
  • Prefira o URL para imagens públicas e o Base64 para ficheiros locais