Przejdź do głównej treści
Polski— Wybierz język
Menu

Ograniczenia: formaty, rozmiar i limity

Lekcja 4 z 12 Zaktualizowano 30 lipca 2026 Początkujący
Na tej stronie
  1. Zasady podstawowe
  2. Akceptowane formaty obrazów
  3. Maksymalny rozmiar: 20 MiB
  4. Liczba obrazów na żądanie: nielimitowana
  5. Kompatybilne modele
  6. Obsługa błędów
  7. Kluczowe wnioski

Zasady podstawowe

Zanim zintegrujesz widzenie Grok ze swoimi aplikacjami, musisz poznać ograniczenia techniczne narzucone przez API xAI. Ignorowanie tych limitów prowadzi do cichych błędów lub odrzucania żądań, które w środowisku produkcyjnym bywają trudne do zdebugowania.

Akceptowane formaty obrazów

API xAI akceptuje dwa formaty plików obrazowych (trzy rozszerzenia: .jpg, .jpeg, .png):

  • JPG (lub JPEG) — najpopularniejszy format dla fotografii
  • PNG — odpowiedni dla zrzutów ekranu, diagramów i obrazów zawierających tekst

Wszystkie inne formaty są odrzucane. Jeśli pracujesz z obrazami WebP, GIF, BMP, TIFF, SVG lub HEIC, musisz je przekonwertować przed wysłaniem:

from PIL import Image

def convert_to_jpeg(source_path, output_path):
    img = Image.open(source_path)
    # Konwersja do RGB (wymagane dla JPEG)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(output_path, "JPEG", quality=90)

Częsty błąd: obrazy RGBA

Pliki PNG z przezroczystością (kanał alfa) są akceptowane bez zmian. Jednak jeśli konwertujesz je do JPEG, musisz najpierw usunąć kanał alfa, ponieważ JPEG nie obsługuje przezroczystości.

Maksymalny rozmiar: 20 MiB

Każdy obraz nie może przekraczać 20 MiB (20 971 520 bajtów). Po przekroczeniu tego limitu API odrzuca żądanie.

Limit ten dotyczy:

  • Pobranego pliku w przypadku podania URL
  • Zdekodowanych danych w przypadku Base64 (nie samego zakodowanego ciągu, który jest o ~33% dłuższy)

Sprawdź rozmiar przed wysłaniem

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"Obraz zbyt duży: {size_mib:.1f} MiB "
            f"(maks. {max_mib} MiB)"
        )
    return size_mib

Kompresuj w razie potrzeby

Dla obrazów zbliżonych do limitu możesz zmniejszyć jakość 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

Liczba obrazów na żądanie: nielimitowana

W przeciwieństwie do innych API wizyjnych, które limitują liczbę obrazów na żądanie, API xAI nie nakłada żadnego limitu. Możesz wysłać tyle obrazów, ile potrzebujesz, w ramach jednego żądania.

Pamiętaj jednak, że:

  • Każdy obraz zużywa od 256 do 1792 tokenów
  • Całkowity kontekst modelu ma maksymalny rozmiar
  • Więcej obrazów = większe opóźnienie i wyższy koszt

Praktyczna rekomendacja

Mimo że limit jest teoretycznie nieograniczony, zachowaj rozsądek:

# Najlepsza praktyka: przetwarzanie partiami
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": "Krótko opisz każdy obraz."
        })

        response = client.responses.create(
            model="grok-4.5",
            input=input_data
        )
        results.append(response)
    return results

Kompatybilne modele

Rozumienie obrazów jest dostępne w modelach grok-4.5 i nowszych. Starsze modele nie obsługują tej funkcji.

Zawsze sprawdzaj model używany w swoim kodzie:

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

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

Obsługa błędów

Przewiduj błędy związane z ograniczeniami, walidując obrazy przed wysłaniem:

def validate_image(path):
    errors = []

    # Sprawdź format
    extension = path.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        errors.append(f"Nieobsługiwany format: {extension}")

    # Sprawdź rozmiar
    size_mib = os.path.getsize(path) / (1024 * 1024)
    if size_mib > 20:
        errors.append(f"Zbyt duży: {size_mib:.1f} MiB (maks. 20)")

    # Sprawdź, czy to prawdziwy obraz
    try:
        img = Image.open(path)
        img.verify()
    except Exception:
        errors.append("Uszkodzony plik lub nieprawidłowy obraz")

    return errors

Kluczowe wnioski

  • Akceptowane są wyłącznie formaty JPG/JPEG i PNG — konwertuj inne
  • Maksymalny rozmiar: 20 MiB na obraz — kompresuj w razie potrzeby
  • Liczba obrazów na żądanie jest nielimitowana, ale każdy obraz zużywa tokeny
  • Tylko modele grok-4.5 i nowsze obsługują widzenie
  • Zawsze waliduj obrazy przed wysłaniem, aby uniknąć cichych błędów