Премини към основното съдържание
Български— Изберете език
Меню

Ограничения: Формати, Размер и Лимити

Урок 4 от 12 Обновен 30 юли 2026 г. Начинаещ
На тази страница
  1. Основни правила
  2. Приети формати на изображения
  3. Максимален размер: 20 MiB
  4. Брой изображения на заявка: Неограничен
  5. Съвместими модели
  6. Обработка на грешки
  7. Ключови изводи

Основни правила

Преди да интегрирате 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 функционалност
  • Винаги валидирайте изображенията преди изпращане, за да избегнете тихи грешки