Salt la conținutul principal
Română— Alege o limbă
Meniu

Constrângeri: Formate, dimensiune și limite

Lecția 4 din 12 Actualizată 30 iulie 2026 Începător
Pe această pagină
  1. Reguli de bază
  2. Formate de imagine acceptate
  3. Dimensiune maximă: 20 MiB
  4. Număr de imagini per cerere: Nelimitat
  5. Modele compatibile
  6. Gestionarea erorilor
  7. Puncte cheie

Reguli de bază

Înainte de a integra viziunea Grok în aplicațiile dumneavoastră, trebuie să cunoașteți constrângerile tehnice impuse de API-ul xAI. Ignorarea acestor limite duce la erori silențioase sau la respingerea cererilor, care pot fi greu de depanat în producție.

Formate de imagine acceptate

API-ul xAI acceptă două formate de fișiere imagine (trei extensii: .jpg, .jpeg, .png):

  • JPG (sau JPEG) — cel mai comun format pentru fotografii
  • PNG — potrivit pentru capturi de ecran, diagrame și imagini cu text

Toate celelalte formate sunt respinse. Dacă lucrați cu imagini WebP, GIF, BMP, TIFF, SVG sau HEIC, trebuie să le convertiți înainte de a le trimite:

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)

Capcană frecventă: Imagini RGBA

Fișierele PNG cu transparență (canal alfa) sunt acceptate ca atare. Totuși, dacă le convertiți în JPEG, trebuie să eliminați mai întâi canalul alfa, deoarece JPEG nu suportă transparența.

Dimensiune maximă: 20 MiB

Fiecare imagine nu trebuie să depășească 20 MiB (20.971.520 de octeți). Dincolo de această limită, API-ul respinge cererea.

Această limită se aplică:

  • Fișierului descărcat în cazul unui URL
  • Datelor decodate în cazul Base64 (nu șirului codat în sine, care este cu ~33% mai lung)

Verificați dimensiunea înainte de trimitere

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

Comprimare dacă este necesar

Pentru imaginile apropiate de limită, puteți reduce calitatea 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

Număr de imagini per cerere: Nelimitat

Spre deosebire de alte API-uri de viziune care limitează numărul de imagini per cerere, API-ul xAI nu impune nicio limită. Puteți trimite câte imagini doriți într-o singură cerere.

Totuși, rețineți că:

  • Fiecare imagine consumă între 256 și 1792 de tokeni
  • Contextul total al modelului are o dimensiune maximă
  • Mai multe imagini = latență și costuri mai mari

Recomandare practică

Deși limita este teoretic nelimitată, rămâneți rezonabili:

# 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

Modele compatibile

Înțelegerea imaginilor este disponibilă pe grok-4.5 și versiuni superioare. Modelele anterioare nu suportă această funcționalitate.

Verificați întotdeauna modelul utilizat în codul dumneavoastră:

VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]

def supports_vision(model):
    return any(model.startswith(m) for m in VISION_MODELS)

Gestionarea erorilor

Anticipați erorile legate de constrângeri prin validarea imaginilor înainte de trimitere:

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

Puncte cheie

  • Sunt acceptate doar formatele JPG/JPEG și PNG — convertiți-le pe celelalte
  • Dimensiune maximă: 20 MiB per imagine — comprimați dacă este necesar
  • Numărul de imagini per cerere este nelimitat, dar fiecare imagine consumă tokeni
  • Doar modelele grok-4.5 și superioare suportă viziunea
  • Validați întotdeauna imaginile înainte de trimitere pentru a evita erorile silențioase