Ограничения: Формати, Размер и Лимити
На тази страница
Основни правила
Преди да интегрирате Grok Vision във Вашите приложения, трябва да познавате техническите ограничения, наложени от xAI API. Игнорирането на тези лимити води до тихи грешки или отхвърлени заявки, които трудно се откриват в продукционна среда.
Приети формати на изображения
xAI API приема два формата на изображение (три разширения: .jpg, .jpeg, .png):
- JPG (или JPEG) — най-често използваният формат за фотографии
- PNG — подходящ за екранни снимки, диаграми и изображения с текст
Всички други формати се отхвърлят. Ако работите с WebP, GIF, BMP, TIFF, SVG или HEIC изображения, трябва да ги конвертирате преди изпращане:
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)
Честа грешка: RGBA изображения
PNG файлове с прозрачност (алфа канал) се приемат така, както са. Въпреки това, ако ги конвертирате в JPEG, първо трябва да премахнете алфа канала, тъй като JPEG не поддържа прозрачност.
Максимален размер: 20 MiB
Всяко изображение не трябва да надвишава 20 MiB (20 971 520 байта). При надвишаване на този лимит API отхвърля заявката.
Този лимит важи за:
- Изтегления файл в случая на URL адрес
- Декодираните данни в случая на Base64 (не за самия кодиран низ, който е с около 33% по-дълъг)
Проверка на размера преди изпращане
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
Компресиране при необходимост
За изображения, близки до лимита, можете да намалите качеството на 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
Брой изображения на заявка: Неограничен
За разлика от други vision API, които ограничават броя изображения на заявка, xAI API не налага лимит. Можете да изпратите толкова изображения, колкото е необходимо, в една единствена заявка.
Имайте предвид обаче, че:
- Всяко изображение консумира между 256 и 1792 токена
- Общият контекст на модела има максимален размер
- Повече изображения = по-голяма латентност и разходи
Практическа препоръка
Дори лимитът теоретично да е неограничен, бъдете разумни:
# 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
Съвместими модели
Разбирането на изображения е достъпно за grok-4.5 и по-нови версии. По-ранните модели не поддържат тази функция.
Винаги проверявайте модела, използван във Вашия код:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Обработка на грешки
Предвидете грешки, свързани с ограниченията, като валидирате изображенията преди изпращане:
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
Ключови изводи
- Приемат се само формати JPG/JPEG и PNG — конвертирайте останалите
- Максимален размер: 20 MiB на изображение — компресирайте при необходимост
- Броят изображения на заявка е неограничен, но всяко изображение консумира токени
- Само модели grok-4.5 и по-нови поддържат vision функционалност
- Винаги валидирайте изображенията преди изпращане, за да избегнете тихи грешки