Ограничения на размер и формат изображений: частые ошибки

Обновление, октябрь 2026. Генерация изображений через Zukko временно недоступна. Актуальный список моделей — страница «Модели»↗ или GET https://api.zukko.pro/v1/models. Ближайшая замена: прямой замены среди доступных моделей нет; для анализа изображений (vision) подойдут модели Claude и GPT, например claude-sonnet-5 или gpt-5.6-sol.

Запрос с изображением — на вход в edit, reference или на вход в vision-модель — ломается иначе, чем обычный текстовый. Текстовая ошибка обычно приходит с внятным сообщением; ошибка с картинкой чаще всего сводится к общему 400 без точного указания, что именно не так с файлом. Ниже — где реально теряются изображения по размеру и формату, и как это проверить, не гадая.

Шлюз не публикует фиксированные числа

У генерации и редактирования изображений (/v1/images/generations) нет единого зафиксированного лимита в мегабайтах или пикселях, который можно один раз запомнить и больше не проверять. Модели разных семейств — линейка nano-banana-2-* и линейка openai-gpt-image-* — валидируют входящий файл каждая по-своему, и именно от конкретной модели зависит, какое разрешение и какой вес файла она примет. Шлюз в этой части в первую очередь передаёт запрос дальше и возвращает ответ модели как есть, а не подменяет его собственной унифицированной проверкой.

Практический вывод: не держите в проекте захардкоженную константу вроде «максимум 10 МБ» — она может быть верна для одной модели и совершенно не подходить для другой. Ориентируйтесь на текст конкретной ошибки, а не на память о прошлом успешном запросе к другой модели.

Как читать ответ на ошибку

Если файл не подошёл по формату или размеру, ответ приходит с кодом 400 и сообщением в поле message — именно в нём обычно написана конкретика: неподдерживаемый формат, слишком большое разрешение, повреждённые данные. Стоит читать это поле буквально, а не по шаблону из документации, потому что формулировка зависит от модели, которая обрабатывает запрос.

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-edit-developer",
    "prompt": "убрать фон, оставить только объект",
    "images": ["data:image/bmp;base64,Qk1..."]
  }' -i

Если модель не умеет работать с конкретным форматом (в примере — BMP), сообщение почти всегда так и назовёт формат прямо, и это самая быстрая подсказка, что нужно перекодировать файл, а не разбираться дальше в структуре запроса.

Безопасный выбор формата

PNG и JPEG на практике принимаются всеми моделями каталога, которые работают с изображениями (у моделей GLM vision нет, им картинки отправлять бессмысленно), — это самый предсказуемый выбор для входного изображения, будь то edit, reference или вход в vision-модель через /v1/messages и /v1/chat/completions. WebP тоже обычно проходит, но если модель вернула ошибку формата на WebP, первое, что стоит попробовать — пересохранить файл в PNG перед кодированием.

Отдельно стоит проверить, что media_type (в Anthropic-схеме) или префикс data:image/...;base64, (в OpenAI-схеме) совпадает с реальным форматом файла, а не с расширением из его имени. Файл, который на самом деле PNG, но подписан как image/jpeg, не всегда даёт явную ошибку — иногда модель просто хуже читает содержимое, и разбираться в этом дольше, чем один раз проверить первые байты файла перед отправкой.

Разрешение исходника имеет значение практически, а не формально

Формальных ограничений на разрешение шлюз не публикует, но на практике сверхвысокое разрешение увеличивает вес base64-строки в теле запроса линейно, а для vision-запросов ещё и число токенов, которые уйдут на обработку картинки. Если задача — редактирование или референс, а не точное распознавание мелких деталей, разумно уменьшить исходник до разрешения, которое всё ещё сохраняет нужные детали, но не тащит за собой лишний вес. Это не требование модели, а способ не упереться в лимит на размер тела запроса раньше, чем в лимит на формат.

Несколько изображений в одном запросе

Поле images в reference- и edit-режимах — массив, и можно передать несколько файлов. Каждый добавленный файл увеличивает вес тела запроса, и при работе с несколькими изображениями высокого разрешения совокупный размер растёт быстрее, чем кажется на глаз. Если запрос с одной картинкой проходит, а с несколькими — нет, вероятная причина не в формате, а в накопленном весе тела: стоит уменьшить разрешение каждого файла или сократить их количество.

Vision-запросы страдают от тех же причин

Всё сказанное выше про формат и вес файла касается не только /v1/images/generations — те же ограничения актуальны, когда изображение идёт на вход текстовой модели с поддержкой vision через /v1/messages или /v1/chat/completions. Разница в том, что там ошибка форматирования картинки чаще маскируется под общий 400 «invalid content», потому что модель в первую очередь ожидает текст, а изображение — лишь один из блоков в content. Если запрос с текстом без картинки проходит, а с картинкой — нет, стоит в первую очередь проверить те же три пункта: формат, соответствие media_type реальному файлу и вес base64-строки, а не искать проблему в остальной части запроса.

Полезная привычка — прогонять тело с картинкой через бесплатный подсчёт токенов перед боевым запросом:

curl https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":[{"type":"image","source":{"type":"base64","media_type":"image/png","data":"iVBORw0KG..."}}]}]}'

Если этот запрос падает с ошибкой формата, а не просто считает токены, — значит проблема действительно в самом изображении, а не в остальной части запроса, и разбираться дальше в модели или ключе смысла нет.

Итог

Проверка перед отправкой сводится к трём вещам: формат файла — PNG или JPEG как самый безопасный выбор, корректность media_type или data-URI префикса, и разумное разрешение файла без лишнего запаса. Дальше — читать сообщение в ответе буквально, потому что оно приходит от конкретной модели и обычно называет причину прямо.