Ошибка 413 при отправке изображений или PDF в AI API: размер запроса и лимиты шлюза

Короткий текстовый запрос работает, но после добавления изображения, PDF или нескольких вложений сервер отвечает 413 Content Too Large, Payload Too Large или Request Entity Too Large. В первую очередь проверьте размер отправляемого тела запроса: он не обязательно совпадает с размером исходного файла на диске.

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

1. Ошибка 413 и переполнение контекста — разные проблемы

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

Признак	Что проверять первым	Какой вывод делать рано
HTTP 413 после добавления большого файла	Размер тела в байтах и ограничения по всей цепочке	Это не доказывает нехватку контекстного окна
context_length_exceeded	Входные токены, историю и бюджет вывода	Маленький файл не обязательно содержит мало токенов
HTTP 415 или неподдерживаемый формат	Content-Type, формат файла и возможности endpoint	Одно сжатие может не помочь
Тайм-аут или 502/504	Время загрузки, тайм-аут шлюза и обработку	Тайм-аут сам по себе не доказывает превышение размера

Некоторые API используют другие статусы для ошибок размера: сверяйте текст ответа с документацией. При явном превышении контекстного окна используйте руководство по сокращению контекста, а не только настройки загрузки файлов.

2. Почему изображение 6 МиБ превращается примерно в 8 МиБ

Некоторые клиенты кодируют файл в Base64 и помещают строку в JSON. Для стандартного Base64 с заполнением, без дополнительных переносов строк:

число символов Base64 = 4 × ceil(размер файла в байтах ÷ 3)

Base64 использует ASCII и обычно увеличивает размер примерно на треть. Файл 6 МиБ содержит 6 291 456 байт; его Base64-представление занимает 8 388 608 байт, то есть 8 МиБ. Префикс data URL, поля JSON, инструкции и история диалога добавляют объём сверх этого значения.

Один МиБ равен 1 048 576 байтам, а МБ обычно означает 1 000 000 байт. Переводите ограничения в байты перед сравнением. Кроме того, клиент может повторно включать то же изображение в историю каждого запроса.

Для PDF сначала выясните способ обработки: бинарная загрузка, Base64, извлечённый текст или изображения отдельных страниц. Небольшой PDF после рендеринга страниц может заметно увеличиться, а после извлечения текста — превысить уже лимит токенов. Размер самого .pdf не даёт полной картины.

3. Измерьте размер локально, без платного вызова

Сохраните следующий код в check-request-size.mjs и используйте Node.js 20 или новее. Скрипт читает только сведения о размере файла, не читает его содержимое, не подключается к сети и не вызывает модель.

import { stat } from 'node:fs/promises';

const [filePath, mode = 'raw'] = process.argv.slice(2);
if (!filePath || !['raw', 'base64'].includes(mode)) {
  console.error('Usage: node check-request-size.mjs <file> [raw|base64]');
  process.exitCode = 1;
} else {
  try {
    const info = await stat(filePath);
    if (!info.isFile()) throw new Error('Not a regular file');
    const bytes = info.size;
    const estimatedBytes = mode === 'base64'
      ? 4 * Math.ceil(bytes / 3)
      : bytes;
    console.log(JSON.stringify({
      fileBytes: bytes,
      mode,
      measuredOrEstimatedBytes: estimatedBytes,
      MiB: Number((estimatedBytes / 1048576).toFixed(3)),
    }, null, 2));
  } catch {
    console.error('Cannot inspect file; check path and permissions.');
    process.exitCode = 1;
  }
}

Команда node check-request-size.mjs "photo.jpg" base64 оценивает размер закодированного файла. Команда node check-request-size.mjs "request.json" raw измеряет сохранённый JSON. Результат raw соответствует телу запроса только если отправляется именно этот файл без последующих изменений и дополнительного кодирования передачи.

Оценка Base64 не является размером всего запроса. multipart добавляет границы и поля; при сжатой передаче могут действовать отдельные ограничения до и после распаковки. Если уже получена строка JSON.stringify(payload), в Node.js её размер в UTF-8 можно измерить через Buffer.byteLength(body, 'utf8'). Свойство строки length не равно числу байтов.

Образцы с ключами, клиентскими файлами и чувствительным текстом обрабатывайте только в контролируемой локальной среде. Не отправляйте их в публичные онлайн-сервисы измерения размера; после диагностики применяйте правила очистки проекта.

4. Найдите слой, который отклоняет запрос

Опишите фактическую цепочку, например: браузер → ваш backend → платформа или прокси → API посредника. Лимит возможен на любом этапе. При одинаковом способе измерения действует наименьший из разрешённых размеров.

Сопоставьте время, ID запроса, журналы шлюза и приложения. Если backend совсем не видит запрос, это указывает на возможный отказ перед ним, но отсутствие записи может быть и проблемой сбора логов. Оформление страницы ошибки и заголовок Server тоже дают лишь косвенные признаки.

Если провайдер явно разрешает отдельный API-вход для проверки, сравните цепочки с тем же аккаунтом и моделью на небольшом несекретном примере. Не пересылайте production-файлы или ключи на незнакомые домены и не ищите предел многократными огромными запросами. Минимальный образец и разумно уменьшенный файл часто дают достаточно информации.

5. Сначала уменьшите содержимое, затем оценивайте лимиты

У изображения можно обрезать ненужный фон, снизить избыточное разрешение или выбрать подходящее сжатие с потерями. Для распознавания текста обязательно проверьте читаемость мелких символов: успешная загрузка не гарантирует качество результата. Смена расширения не преобразует формат файла.

У PDF можно выбрать нужные страницы или извлекать текст по разделам. Разбиение способно потерять связи в таблицах и вёрстке, поэтому сохраняйте номера страниц и сведения для объединения результатов. Дополнительные части могут увеличить число вызовов и суммарные расходы.

Если API поддерживает предварительную загрузку и последующую ссылку на ID файла, это позволяет не встраивать файл заново в каждый JSON. Но отдельный endpoint загрузки всё равно имеет ограничения размера, формата, срока хранения и доступа. Ссылка на изображение может уменьшить JSON, если интерфейс её поддерживает, но не отменяет проверки файла на стороне провайдера. Не делайте личные документы публичными ради ссылки. О форматах отправки читайте в руководстве по изображениям.

Менять конфигурацию стоит только на сервере, которым вы управляете. Например, client_max_body_size в Nginx ограничивает принимаемое тело запроса. Задайте обоснованный конечный размер в подходящей области конфигурации и проверьте остальные слои. Жёсткий лимит хостинга может не изменяться из кода проекта. Не отключайте ограничения без оценки памяти, временного диска, параллелизма, времени и расходов.

6. Повторять ли запрос и как проверить исправление

При постоянном ограничении тот же запрос обычно снова завершится ошибкой. Временное ограничение иногда сопровождается Retry-After; действуйте по документации API, без бесконечных повторов. Отсутствие результата не гарантирует отсутствие списания, особенно при автоматических повторах клиента, загрузке частями или преобразованиях у посредника. Сверяйте записи по ID запроса.

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

Поддержке можно отправить следующую сводку без клиентского файла:

Время и часовой пояс:
Домен, путь API и модель без ключа:
HTTP-статус и код ошибки:
Формат исходного файла и размер в байтах:
Передача: бинарный файл / Base64 / текст / ID файла / URL
Полный размер тела: измеренное значение или «неизвестно»
ID запроса, если есть:
Работает ли маленький образец и уменьшенный файл:
Проходит ли запрос через собственный backend или прокси:

Источники, просмотренные 07.10.2026: MDN: 413 Content Too Large, MDN: Base64, Nginx: client_max_body_size. Они описывают протокол и компоненты, а не текущие лимиты всех API-провайдеров.