Incorpore imagens com o NextPDF Connect

Visão geral

Incorpore uma imagem em um arquivo Portable Document Format (PDF) com o NextPDF Connect. Use como origem um caminho de arquivo que o servidor consiga ler ou um data URI base64 inline. Você usa create_pdf, add_image e output_pdf — todas são ferramentas Core. O NextPDF desenha a imagem como um XObject de imagem, pintado pelo operador Do (ISO 32000-2 §8.9).

Instalação

composer require nextpdf/server

Vincule um transporte. O NextPDF oferece suporte aos formatos raster PNG, JPEG e GIF.

Visão conceitual

add_image recebe um source e o resolve na seguinte ordem fixa:

Data URI — uma string que começa com data:. O NextPDF identifica o tipo Multipurpose Internet Mail Extensions (MIME), decodifica o payload base64 em um arquivo temporário, incorpora a imagem e, em seguida, remove o arquivo temporário.
Base64 puro — o NextPDF decodifica uma string base64 longa e a trata como PNG.
Caminho de arquivo — o NextPDF trata qualquer outro valor como um caminho no sistema de arquivos que o processo do servidor precisa conseguir ler.

A imagem aparece em x/y, em unidades de usuário (milímetros por padrão). Se você passar apenas width, o NextPDF calcula a altura para preservar a proporção. Se você passar width e height, o NextPDF dimensiona a imagem para essas dimensões exatas. O objeto incorporado é um objeto externo pintado no conteúdo da página (ISO 32000-2 §8.8).

Superfície da API

Ferramenta	Função	Nível de risco
`create_pdf`	Abrir uma sessão	Seguro
`add_image`	Incorporar uma imagem a partir de um caminho ou data URI	Cuidado
`output_pdf`	Renderizar e retornar o PDF	Aprovação Obrigatória / Revisão (base64)

O catálogo de ferramentas é o catálogo oficial. As ferramentas disponíveis dependem do tier instalado.

Exemplo de código — Início rápido

create_pdf (A4 retrato, título) → document_id.
add_image com source definido como um caminho absoluto, x, y, width.
add_image com source definido como um URI data:image/png;base64,... e width e height explícitos.
output_pdf → base64.

Exemplo de código — Produção

Use um data URI para uma imagem que o host tenha gerado em memória, como a renderização de um gráfico ou uma captura de tela. Use um caminho de arquivo para um ativo que já existe no servidor. Sempre use caminhos absolutos. Um caminho relativo é resolvido em relação ao diretório de trabalho do servidor, que normalmente não é o diretório do host. Antes de continuar, confirme que a resposta de add_image indica que a imagem está na página esperada.

Casos extremos e pegadinhas

Caminho não encontrado. Um caminho de arquivo inexistente retorna um erro informando que a imagem não foi encontrada.
Formato não suportado. O NextPDF rejeita SVG, BMP e WebP. Converta a imagem primeiro.
Base64 / data URI malformado. Um payload inválido ou um data URI sem o separador de vírgula retorna um erro de decodificação.
Imagem grande demais. Uma imagem maior que a página é recortada na borda, não rejeitada. Calcule width/height em relação à página, descontadas as suas margens (A4 retrato tem 210×297 mm).

Desempenho

O tamanho da saída escala com o conteúdo da imagem. Duas imagens pequenas normalmente têm de 10 a 50 KB. O orçamento de incorporação de imagens é mais amplo que o orçamento somente de texto. Esta página usa o perfil structural.

Notas de segurança

O modo de caminho de arquivo lê do sistema de arquivos do servidor com os privilégios do processo do servidor. Restrinja que caminhos o host pode passar. Não permita que chamadores não confiáveis apontem source para arquivos arbitrários do servidor. O modo base64 carrega os bytes inline, portanto evita a exposição de caminhos do servidor.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Uma imagem é um XObject de imagem pintado por `Do`.	ISO 32000-2	§8.9
Imagens são objetos externos pintados no conteúdo da página.	ISO 32000-2	§8.8

Contexto comercial

Não se aplica — todas as ferramentas estão incluídas no Core.

Disponibilidade por transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	Payloads base64 grandes aumentam o tamanho do frame stdio.
REST	Sim	Prefira multipart ou um caminho de servidor para ativos grandes.
gRPC	Sim	Unário; os limites de tamanho de mensagem se aplicam ao base64 inline.

Nível de risco HITL

create_pdf é Seguro, add_image é Cuidado e output_pdf é Aprovação Obrigatória — rebaixado para Revisão no modo base64. A leitura em modo de caminho ocorre no lado do servidor e não é controlada separadamente, portanto restrinja-a na camada de política (níveis de risco HITL).

Envelope JSON do portão de confirmação

Saída base64 aqui:

{ "allowed": true }