Restrições: Formatos, Tamanho e Limites
Nesta página
Regras Fundamentais
Antes de integrar a visão do Grok nas suas aplicações, precisa de conhecer as restrições técnicas impostas pela API da xAI. Ignorar estes limites resulta em erros silenciosos ou pedidos rejeitados, difíceis de depurar em produção.
Formatos de Imagem Aceites
A API da xAI aceita dois formatos de ficheiro de imagem (três extensões: .jpg, .jpeg, .png):
- JPG (ou JPEG) — o formato mais comum para fotografias
- PNG — adequado para capturas de ecrã, diagramas e imagens com texto
Todos os outros formatos são rejeitados. Se trabalhar com imagens WebP, GIF, BMP, TIFF, SVG ou HEIC, deve convertê-las antes do envio:
from PIL import Image
def convert_to_jpeg(source_path, output_path):
img = Image.open(source_path)
# Convert to RGB (required for JPEG)
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
img.save(output_path, "JPEG", quality=90)
Armadilha Comum: Imagens RGBA
Ficheiros PNG com transparência (canal alfa) são aceites tal como estão. No entanto, se os converter para JPEG, deve remover primeiro o canal alfa, pois o JPEG não suporta transparência.
Tamanho Máximo: 20 MiB
Cada imagem não pode exceder 20 MiB (20.971.520 bytes). Acima deste valor, a API rejeita o pedido.
Este limite aplica-se:
- Ao ficheiro descarregado, no caso de um URL
- Aos dados descodificados, no caso de Base64 (não à cadeia codificada em si, que é ~33% mais longa)
Verificar o Tamanho Antes do Envio
import os
def check_size(image_path, max_mib=20):
size = os.path.getsize(image_path)
size_mib = size / (1024 * 1024)
if size_mib > max_mib:
raise ValueError(
f"Image too large: {size_mib:.1f} MiB "
f"(max {max_mib} MiB)"
)
return size_mib
Comprimir, Se Necessário
Para imagens próximas do limite, pode reduzir a qualidade do JPEG:
def compress_image(path, quality=80, max_size_mib=20):
img = Image.open(path)
buffer = io.BytesIO()
img.save(buffer, "JPEG", quality=quality)
while buffer.tell() > max_size_mib * 1024 * 1024 and quality > 20:
quality -= 10
buffer = io.BytesIO()
img.save(buffer, "JPEG", quality=quality)
buffer.seek(0)
return buffer
Número de Imagens por Pedido: Ilimitado
Ao contrário de outras APIs de visão que limitam o número de imagens por pedido, a API da xAI não impõe qualquer limite. Pode enviar tantas imagens quanto necessário num único pedido.
No entanto, tenha em conta que:
- Cada imagem consome entre 256 e 1792 tokens
- O contexto total do modelo tem um tamanho máximo
- Mais imagens = maior latência e custo
Recomendação Prática
Embora o limite seja teoricamente ilimitado, mantenha-se razoável:
# Best practice: process in batches
def analyze_batch(images, batch_size=10):
results = []
for i in range(0, len(images), batch_size):
batch = images[i:i + batch_size]
input_data = []
for img in batch:
input_data.append({
"type": "input_image",
"image_url": img,
"detail": "low"
})
input_data.append({
"type": "input_text",
"text": "Briefly describe each image."
})
response = client.responses.create(
model="grok-4.5",
input=input_data
)
results.append(response)
return results
Modelos Compatíveis
A compreensão de imagens está disponível nos modelos grok-4.5 e superiores. Modelos anteriores não suportam esta funcionalidade.
Verifique sempre o modelo utilizado no seu código:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Gestão de Erros
Antecipe erros relacionados com restrições validando as imagens antes do envio:
def validate_image(path):
errors = []
# Check format
extension = path.lower().rsplit(".", 1)[-1]
if extension not in ("jpg", "jpeg", "png"):
errors.append(f"Unsupported format: {extension}")
# Check size
size_mib = os.path.getsize(path) / (1024 * 1024)
if size_mib > 20:
errors.append(f"Too large: {size_mib:.1f} MiB (max 20)")
# Check that it is a real image
try:
img = Image.open(path)
img.verify()
except Exception:
errors.append("Corrupted file or not a valid image")
return errors
Pontos-chave
- Apenas os formatos JPG/JPEG e PNG são aceites — converta os outros
- Tamanho máximo: 20 MiB por imagem — comprima se necessário
- O número de imagens por pedido é ilimitado, mas cada imagem consome tokens
- Apenas os modelos grok-4.5 e superiores suportam visão
- Valide sempre as imagens antes do envio para evitar erros silenciosos