Ograniczenia: formaty, rozmiar i limity
Na tej stronie
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