Как это работает

Файл с именем report.pdf не обязательно является PDF, а файл вообще без расширения обычно всё равно поддаётся опознанию. Поэтому первое, что происходит, — мы читаем начальные байты загрузки и сверяем их с известными сигнатурами форматов.

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

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

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

Изменение размера изображения занимает заметно меньше секунды, поэтому выполняется внутри запроса, и ответ уже содержит результат. Отрисовка длинного документа или перекодирование видео — нет, поэтому такие задачи ставятся в очередь, и их разбирает отдельный пул обработчиков.

Вам никогда не нужно гадать, что вы получили. Завершённая задача возвращается с результатом; поставленная в очередь — с идентификатором, позицией в очереди и оценкой, и вы опрашиваете её или ждёте письма.

Сайт, API и конвертация по почте — три двери в один конвейер. Они различаются только тем, как определяется вызывающая сторона: сессионная кука, bearer-токен или отправитель письма, — а дальше выполняется ровно тот же код.

Это осознанное ограничение, а не деталь реализации. Две реализации «проверь квоту, распознай байты, обезопась архив» — это способ, которым одна из них однажды пропустит шаг именно для тех, кто заметит это в последнюю очередь.