Встраивание изображений через NextPDF Connect

Краткий обзор

Встраивайте изображения в PDF-файлы через NextPDF Connect. Источником может быть путь к файлу, который сервер может прочитать, или встроенный data URI в формате base64. Для этого используются create_pdf, add_image и output_pdf; все три инструмента входят в Core. NextPDF отрисовывает изображение как image XObject, который отображается оператором Do (ISO 32000-2 §8.9).

Установка

composer require nextpdf/server

Подключите транспорт. NextPDF поддерживает растровые форматы PNG, JPEG и GIF.

Обзор концепции

add_image принимает source и разрешает его в строго заданном порядке:

Data URI — строка, начинающаяся с data:. NextPDF разбирает тип Multipurpose Internet Mail Extensions (MIME), декодирует полезную нагрузку base64 во временный файл, встраивает его, затем удаляет временный файл.
Необработанный base64 — NextPDF декодирует длинную строку base64 и обрабатывает её как PNG.
Путь к файлу — все остальные значения NextPDF обрабатывает как путь в файловой системе, который должен быть доступен для чтения серверному процессу.

Изображение размещается в координатах x/y, в пользовательских единицах (по умолчанию — в миллиметрах). Если передать только width, NextPDF вычислит высоту с сохранением соотношения сторон. Если передать и width, и height, NextPDF масштабирует изображение точно до этих размеров. Встроенный объект — это внешний объект, отображаемый в содержимом страницы (ISO 32000-2 §8.8).

Поверхность API

Инструмент	Роль	Уровень риска
`create_pdf`	Открыть сессию	Безопасно
`add_image`	Встроить изображение по пути или из data URI	Осторожно
`output_pdf`	Сформировать и вернуть PDF	Требуется одобрение / Проверка (base64)

Справочным источником служит Каталог инструментов. Доступные инструменты зависят от установленного уровня.

Пример кода — быстрый старт

create_pdf (A4, книжная ориентация, заголовок) → document_id.
add_image с параметром source, заданным как абсолютный путь, и параметрами x, y, width.
add_image с параметром source, заданным как URI data:image/png;base64,..., и явно заданными width и height.
output_pdf → base64.

Пример кода — продакшен

Используйте data URI для изображения, которое хост создал в памяти, например для отрисованной диаграммы или снимка экрана. Используйте путь к файлу для ресурса, который уже есть на сервере. Всегда указывайте абсолютные пути. Относительный путь разрешается относительно рабочего каталога сервера, который обычно не совпадает с каталогом хоста. Прежде чем продолжить, убедитесь, что ответ add_image подтверждает размещение изображения на ожидаемой странице.

Граничные случаи и подводные камни

Путь не найден. Если путь к файлу отсутствует, возвращается ошибка “изображение не найдено”.
Неподдерживаемый формат. NextPDF отклоняет SVG, BMP и WebP. Сначала преобразуйте изображение.
Некорректный base64 / data URI. Некорректная полезная нагрузка или data URI без разделителя-запятой приводит к ошибке декодирования.
Слишком большое изображение. Изображение, размер которого превышает размер страницы, обрезается по краю, а не отклоняется. Вычисляйте width/height относительно страницы за вычетом её полей (A4 в книжной ориентации — 210×297 мм).

Производительность

Размер вывода растёт вместе с объёмом данных изображения. Два небольших изображения обычно занимают 10–50 КБ. Для встраивания изображений бюджет больше, чем для одного текста. На этой странице используется профиль structural.

Замечания по безопасности

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

Соответствие стандартам

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Изображение является image XObject, отображаемым оператором `Do`.	ISO 32000-2	§8.9
Изображения являются внешними объектами, отображаемыми в содержимом страницы.	ISO 32000-2	§8.8

Коммерческий контекст

Неприменимо — все инструменты входят в Core.

Доступность транспортов

Транспорт	Доступно	Примечания
MCP (stdio) — транспорт	Да	Большие полезные нагрузки base64 увеличивают размер кадра stdio.
REST	Да	Для больших ресурсов предпочтительнее multipart или путь на сервере.
gRPC	Да	Унарный; к встроенному base64 применяются ограничения на размер сообщения.

Уровень риска HITL

У create_pdf уровень Safe, у add_image — Caution, у output_pdf — Approval Required, который в режиме base64 понижается до Review. В режиме пути чтение выполняется на стороне сервера и не проходит через отдельный гейт, поэтому ограничьте его на уровне политики (уровни риска HITL).

JSON-конверт гейта подтверждения

Здесь вывод в base64:

{ "allowed": true }