Como Gerar OG Images e PDFs Automáticos com MarkupGo em 2026

Você pode gerar uma OG image previsível com um template, variáveis e a API de imagem do MarkupGo. Para PDF, a lógica também aceita URL, HTML, template e Markdown. O trabalho não termina no endpoint: trate o resultado como arquivo temporário, mantenha a chave no backend e use cache para não renderizar a cada visita.

Uma imagem social e um PDF automático resolvem problemas parecidos, mas não são o mesmo artefato. A primeira precisa ser legível em um card. O segundo precisa respeitar páginas, margens e quebras. O MarkupGo reúne APIs de imagem, PDF, templates e tarefas em uma plataforma que usa HTML, CSS e JavaScript para criar esses resultados.

O caminho seguro é pensar em um Pipeline de Card Repetível. Em vez de montar uma arte manual para cada URL, você transforma dados normalizados em um template versionado, renderiza uma tarefa e guarda o resultado onde sua aplicação precisa dele.

O que uma API de renderização automatiza?

Uma API de renderização recebe uma fonte visual e devolve um arquivo. No MarkupGo, a documentação pública lista APIs para tarefas, PDFs, imagens, templates, transformação de imagem, cliente Node e outros recursos. Para PDF, a documentação descreve entradas por URL, HTML, template e Markdown.

Isso permite usar o mesmo conjunto de dados de um CMS, planilha ou worker para produzir uma thumbnail, uma OG image, um relatório ou um material de download. O ganho não é “gerar design por mágica”. É retirar trabalho repetitivo de um fluxo que já tem layout definido.

O protocolo Open Graph define metadados como og:title, og:type, og:image e og:url. Ele não fixa uma dimensão única para a imagem. Para um card social, 1200×630 é um formato de trabalho recorrente e útil quando seu template foi desenhado para ele; valide sempre o recorte na rede onde o link será compartilhado.

A arquitetura: dados, template, tarefa e arquivo final

A API não deve receber conteúdo solto de qualquer lugar. Antes da chamada, normalize título, subtítulo, autor, categoria, URL de imagem e versão do template. Assim, um título longo não muda o contrato entre seu CMS e o layout.

Template e variáveis

O template é o lugar para HTML, CSS e JavaScript do layout. Mantenha-o em controle de versão. Também use URLs HTTPS estáveis para logos, fontes e imagens externas. Um asset removido depois da publicação pode gerar uma imagem incompleta mesmo quando seu endpoint continua respondendo.

Não reutilize cegamente o CSS do card no PDF. A imagem social pede hierarquia rápida e pouco texto. O PDF precisa de regras de impressão, margens e quebra de página. Os dados podem ser compartilhados; as regras de layout, não necessariamente.

Autenticação no backend

A documentação de PDF mostra POST /api/v1/pdf com o cabeçalho x-api-key. A documentação de imagem mostra POST https://api.markupgo.com/api/v1/image e também usa x-api-key. Essa chave pertence ao servidor, a uma função protegida ou a um worker. Nunca a envie para JavaScript público, HTML do navegador ou repositório.

Um teste mínimo de imagem por URL, baseado no formato documentado, pode ficar em uma rota interna:

curl -X POST "https://api.markupgo.com/api/v1/image" \
  -H 'x-api-key: ***' \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"url","url":"https://exemplo.com/card"}}'

Troque a URL pelo endereço que seu serviço controla. Para um template, consulte a documentação de templates antes de definir campos do payload. Não invente nomes de variáveis a partir de exemplos de outra API.

Tarefa, URL de resultado e expiração

A resposta de PDF é uma tarefa. Isso muda a implementação: seu código precisa consultar o estado antes de usar o arquivo. A documentação também descreve expiration, que apaga automaticamente o arquivo e o registro da tarefa. Tarefas expiradas são varridas a cada minuto, e a URL pode continuar acessível por cerca de 60 segundos adicionais.

Essa expiração é útil para documentos temporários. Ela não substitui uma política de privacidade, nem confirma região de processamento, SLA, DPA ou adequação a dados sensíveis. Se o PDF precisa continuar disponível, copie o arquivo concluído para o seu storage antes de depender de uma URL temporária.

Tutorial: gere uma OG image previsível

1. Defina o contrato de dados e o tamanho

Comece com um caso repetível: artigo, página de produto ou página de aplicativo. Defina os campos que realmente cabem no card: título, etiqueta, imagem e identidade visual. Limite o título no próprio template. Não espere que uma string longa “se ajuste” sem uma regra de tipografia.

Use um template específico para o formato escolhido. Se você adotar 1200×630, trate largura, altura, espaçamento e área segura como parte do contrato. A API cuida do render; as decisões de legibilidade continuam sendo suas.

2. Versione o template e estabilize os assets

Inclua a versão do template na sua chave de cache. Quando o CSS mudar, a nova versão produz uma imagem nova. Quando só o título mudar, apenas aquele card precisa ser atualizado. Logos, fotos e fontes devem ter URLs estáveis e acessíveis no momento do render.

Evite montar a OG image a cada pageview. O visitante não precisa pagar com espera, e você não precisa gastar créditos repetindo a mesma operação. Gere no publish ou quando o conteúdo mudar.

3. Faça cache por hash do conteúdo

Uma chave simples pode combinar o identificador do post, a versão do template e um hash do conteúdo visual. O pseudofluxo é: calcular chave; procurar arquivo já salvo; se não existir, solicitar a tarefa; ao concluir, salvar a URL final no seu storage; atualizar og:image.

A parte de retry deve ser idempotente. Isso significa que uma repetição da mesma solicitação não cria resultados conflitantes. Guarde a chave, o identificador da tarefa, o status e o erro recebido. Se a chamada falhar por asset inválido, corrija o asset antes de repetir. Se o worker cair após criar a tarefa, a chave permite retomar a consulta em vez de disparar vários renders.

Tutorial: gere um PDF sem transformar card social em documento

A documentação oficial informa que o MarkupGo gera PDF a partir de URL, HTML, template e Markdown. Escolha a entrada pelo que você já possui. Uma página viva pode ser adequada quando o documento é a própria página. Um template ou HTML dedicado dá mais controle para proposta, relatório e lead magnet. Markdown é útil quando seu conteúdo começa como texto estruturado.

1. Use CSS de impressão e quebras explícitas

Crie um layout próprio para o PDF. Defina margens, fonte, largura de tabelas e quebras de página antes de automatizar em lote. Um card com texto grande pode funcionar muito bem numa imagem e muito mal numa página A4. Teste com título longo, acentos, imagem externa e mais de uma página.

A documentação de PDF do MarkupGo é a referência para o endpoint, a autenticação, a tarefa e a expiração. Não trate Office to PDF como recurso estável sem teste: a documentação geral o marca como BETA.

2. Copie o resultado quando a retenção importar

Se o arquivo será baixado apenas logo após uma ação, uma expiração pode fazer sentido. Se ele precisa ficar em uma área de membros, página de vendas ou histórico do cliente, copie o resultado para um armazenamento que você controla. Registre o caminho final no seu banco antes de mostrar o download.

Produção: cache, expiração, retry e logs

O endpoint é só uma etapa. A operação confiável vem de decisões simples e explícitas:

Também evite renderizar dados pessoais sensíveis até entender as garantias que o seu caso exige. A documentação pública auditada não confirmou região de processamento, SLA, DPA, certificações de privacidade ou webhook. Isso não prova ausência; apenas impede tratar esses pontos como confirmados.

MarkupGo, screenshot API ou Playwright/Puppeteer?

A escolha depende do que você quer renderizar e de quem vai operar a infraestrutura. Screenshot de URL captura uma página já pronta. Template API produz um layout repetível. Browser próprio oferece flexibilidade, mas transfere a operação para você.

O Playwright é uma ferramenta de automação de browsers. O Puppeteer é uma biblioteca Node para controlar Chrome e Firefox. Eles podem ser a escolha certa quando você precisa do controle do browser e aceita cuidar de atualização, memória, fontes, fila, segurança e observabilidade.

A leitura do Runzos é objetiva: uma API pode reduzir a superfície operacional inicial, mas não elimina engenharia. Para um fluxo novo, valide template, consumo e armazenamento antes de assumir que operar Chromium será mais barato ou que créditos serão mais caros.

Preço, créditos e como testar sem inventar custo por imagem

A pesquisa registrou um snapshot da página de preços em 9 de agosto de 2026. Uma nova consulta no mesmo dia confirmou que a página continua acessível e exibe referências a créditos e teste com 100 créditos, mas preços e regras comerciais podem mudar. Consulte os planos e créditos atuais antes de contratar.

A divisão de preço por créditos não é custo por imagem ou PDF. A pesquisa não confirmou quantos créditos cada configuração consome. Use o teste para medir o seu caso: um card simples, um título longo, uma imagem remota e um PDF com duas páginas. Só então projete volume.

O MarkupGo também aparece no registro interno do Runzos como oferta lifetime ativa, sem cupom confirmado. Não assuma que o lifetime deal é ilimitado, vitalício em créditos, mais barato que o plano mensal ou disponível para sempre. As condições devem ser lidas na oferta no momento da decisão.

Quando MarkupGo não vale a pena?

MarkupGo não é a resposta automática para toda imagem ou PDF. Uma captura simples de uma página existente pode pedir uma screenshot API. Um produto com alto volume, equipe experiente e necessidade real de controlar o navegador pode justificar Playwright ou Puppeteer próprios. Um projeto sem layout repetível talvez não precise de uma camada de template.

Também pause a decisão se seu caso exige requisitos formais de dados que não foram confirmados publicamente. Sem uma resposta documental adequada ao seu cenário, não transforme suposição em requisito atendido.

FAQ: dúvidas sobre OG images, PDFs e MarkupGo

Qual tamanho devo usar para uma OG image?

O Open Graph não estabelece uma dimensão única obrigatória. Um template em 1200×630 é uma escolha prática comum para cards sociais, desde que você teste o recorte e a legibilidade no canal onde o link será distribuído. Trate a dimensão como regra do seu template, não como promessa do protocolo.

Posso gerar PDF de Markdown?

Sim. A documentação de PDF do MarkupGo lista Markdown entre as entradas suportadas, além de URL, HTML e template. Escolha Markdown quando o conteúdo nasce como texto estruturado. Para controle visual de páginas, ainda defina CSS de impressão e teste quebras, fontes e assets externos.

Playwright é gratuito. Por que não usar sempre?

A licença não é o único custo. Ao rodar um browser próprio, você assume atualização, memória, fontes, fila, observabilidade e segurança. Isso pode compensar quando o controle vale o esforço. Para validar um fluxo repetível, uma API gerenciada pode reduzir o trabalho inicial, desde que você aceite créditos e dependência do fornecedor.

O plano gratuito basta para testar?

O snapshot de 9 de agosto de 2026 registrou 100 créditos mensais no teste gratuito, com recursos limitados. Use-o para validar um template real e observar consumo. Não use esse número como garantia futura: confira a página de preços antes de planejar produção.

Como evito renderizar a cada visita?

Gere a imagem quando o conteúdo ou template mudar. Crie uma chave com identificador do conteúdo, versão do template e hash dos dados visuais. Se a chave já tiver um arquivo válido no seu storage, reutilize-o. Se não tiver, crie ou consulte a tarefa e salve o resultado para as próximas visitas.

Conclusão: teste a arquitetura antes de escalar

MarkupGo é útil quando você precisa transformar dados em cards e PDFs repetíveis sem começar pela operação de um browser headless. O valor vem de ligar template, tarefa, cache e storage com cuidado. Meça créditos no seu fluxo, trate URLs temporárias como temporárias e mantenha o segredo da API no backend.

Ver oferta lifetime do MarkupGo no Runzos. Leia as condições atuais da oferta antes de decidir: não há cupom confirmado neste artigo.