Ошибка 413: запрос слишком большой — как обойти

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

413 отличается от остальных ошибок шлюза тем, что до логики API вообще не доходит: сервер отклоняет тело запроса ещё на уровне приёма, до проверки ключа, баланса или модели. Если запрос с изображением падает с 413, это почти всегда значит одно — тело запроса слишком тяжёлое, а не то, что что-то не так с ключом или с содержимым картинки.

Откуда берётся лишний вес

Чаще всего 413 ловят при передаче изображения через data URL — data:image/png;base64,... прямо внутри JSON-тела. Base64-кодирование не бесплатное: оно увеличивает размер данных примерно на треть от исходного веса файла. Фотография в 6 МБ превращается в строку около 8 МБ, а если в одном запросе передаётся сразу несколько изображений — например, в reference-режиме с массивом images — вес складывается, и совокупное тело быстро вырастает за пределы того, что сервер готов принять.

Точное числовое значение лимита шлюз не публикует и не фиксирует как гарантию — оно относится к инфраструктуре приёма запросов, а не к бизнес-логике API, и может отличаться в зависимости от маршрута. Поэтому надёжнее относиться к 413 как к сигналу «тело слишком большое прямо сейчас», а не пытаться заранее посчитать точный порог в байтах и держать его в конфиге.

Первое решение: URL вместо data URL

Поле images в /v1/images/generations принимает не только data URL, но и обычную ссылку на файл:

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": ["https://example.com/source.png"]
  }'

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

Если ссылки нет и нужен data URL

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

• уменьшить разрешение до того, что реально нужно для задачи — для reference и edit не требуется исходник в разрешении печати;
• пересохранить в JPEG с разумным качеством сжатия вместо PNG, если картинка фотографическая, а не графика с текстом или острыми контурами — PNG для фото весит заметно больше при сравнимом визуальном качестве;
• убрать из запроса лишние изображения, если используется reference-режим с массивом images и часть образцов не критична для результата.

Каждый из этих шагов снижает вес base64-строки напрямую, без потери того, что действительно нужно модели для генерации.

Это не токенный лимит и не баланс

413 стоит отличать от ошибок, которые приходят уже после того, как сервер принял тело: 401 за ключ, 402 за пустой баланс, 400 model_not_found за опечатку в имени модели. Все они возвращаются с телом ответа в формате JSON и полем message, объясняющим причину. 413 обычно приходит без такого информативного JSON-тела — это уровень транспорта, а не API, и первым делом стоит смотреть не на текст ошибки, а на реальный размер того, что вы отправляете.

Как проверить размер тела перед отправкой

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

echo -n '{"model":"...", "images":["data:image/png;base64,..."]}' | wc -c

Если результат исчисляется мегабайтами, а не килобайтами, это уже сигнал попробовать URL вместо data URL или уменьшить исходное изображение, не дожидаясь фактического 413 от сервера.

Для reference и edit с несколькими образцами

В reference-режиме массив images может содержать больше одного файла. Если один образец в высоком разрешении проходит, а добавление второго и третьего приводит к 413 — дело не в конкретном файле, а в сумме их весов. В такой ситуации разумнее оставить один самый информативный образец или заменить часть data URL на обычные ссылки, если файлы доступны публично.

Vision-запросы к текстовым моделям тоже подвержены 413

Та же логика работает при отправке изображения в текстовую модель с поддержкой vision через /v1/messages или /v1/chat/completions. Если в диалоге накопилось несколько сообщений с картинками, закодированными как base64, суммарный вес истории переписки растёт с каждым новым изображением. Если 413 появился не сразу, а после нескольких сообщений подряд — вероятная причина не в последнем файле, а в накопленном весе всей истории целиком. В таком случае помогает не хранить старые изображения в контексте диалога буквально, а держать только текстовое описание уже обработанной картинки, если модели больше не нужно видеть исходный файл повторно.

Итог

413 — это ошибка транспортного уровня, не бизнес-логики API: ключ, баланс и корректность модели здесь ни при чём. Причина почти всегда одна — тело запроса физически слишком тяжёлое из-за base64-кодирования одного или нескольких изображений. Самое надёжное решение — передавать изображения ссылкой там, где это возможно, а для приватных файлов уменьшать разрешение и переходить на JPEG для фотографического контента вместо PNG.