API de Markdown para imagem: gerar PNG com cURL, Node.js, Python e n8n

Uma exportação manual é suficiente para uma imagem. Torna-se um bloqueio quando um produto precisa de transformar cada relatório de IA, registo de alterações, resposta de suporte ou publicação social num recurso visual consistente. Uma API de Markdown para imagem leva a renderização para o código: envia Markdown, escolhe formato e tema, recebe um URL ou ficheiro binário e guarda o resultado onde a aplicação precisa.

Este guia constrói uma integração real com a API do MarkdownToImage. Começamos com cURL, implementamos o mesmo fluxo em Node.js e Python, configuramos o n8n e adicionamos as proteções de produção que os exemplos rápidos costumam omitir.

O endpoint e os limites deste artigo foram verificados a 2 de agosto de 2026 na documentação oficial da API. As quotas e os planos podem mudar; confirme a página de preços atual antes de estimar custos de produção.

Inicie sessão no MarkdownToImage e crie um token na área API Tokens. Trate-o como uma palavra-passe: não o coloque no código-fonte, em ficheiros Markdown, capturas, JavaScript do browser ou exportações de fluxos.

Para testes locais, exponha-o como variável de ambiente:

export MARKDOWN_TO_IMAGE_API_TOKEN="mti_your_token_here"

Em produção, use o armazenamento de segredos cifrado da sua plataforma. Se um token aparecer num repositório público ou registo, revogue-o e crie outro em vez de tentar apenas esconder o commit antigo.

A API oferece atualmente uma quota mensal gratuita com marca de água. A utilização sem marca e os volumes superiores dependem de créditos ou do plano vigente. Confirme as páginas oficiais ao implementar e não trate a quota atual como uma garantia permanente do produto.

O endpoint de geração aceita JSON e usa autenticação Bearer. Este pedido cria um PNG com 1200 píxeis de largura e tema escuro do GitHub:

curl -X POST https://markdowntoimage.com/api/v1/images/generate \
  -H "Authorization: Bearer $MARKDOWN_TO_IMAGE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Weekly release\n\n- Faster exports\n- Clearer reports\n- One automated workflow",
    "format": "png",
    "width": 1200,
    "quality": 2,
    "theme": "github-dark",
    "mode": "url"
  }'

Uma resposta bem-sucedida em modo URL contém data.imageUrl. O endereço é temporário: abri-lo confirma a renderização, mas não cria armazenamento permanente. Descarregue o ficheiro rapidamente e envie-o para o seu armazenamento de objetos, CMS ou biblioteca multimédia.

Apenas markdown é obrigatório, mas definições explícitas tornam a saída automatizada previsível.

Use JPEG para fotografia quando a compressão com perdas é aceitável. PNG é indicado para código, diagramas e interfaces nítidas. WebP reduz largura de banda se todos os consumidores o suportarem. Embora PDF use o mesmo endpoint, é uma saída de documento e não uma imagem social comum.

O script Node.js abaixo chama a API, verifica a resposta HTTP, descarrega o resultado temporário e grava um ficheiro real. Usa o fetch global das versões atuais do Node.js.

import { writeFile } from "node:fs/promises";

const token = process.env.MARKDOWN_TO_IMAGE_API_TOKEN;
if (!token) throw new Error("MARKDOWN_TO_IMAGE_API_TOKEN is required");

const response = await fetch("https://markdowntoimage.com/api/v1/images/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    markdown: "# Build report\n\n- Tests: **passed**\n- Deploy: **ready**",
    format: "png",
    width: 1200,
    quality: 2,
    theme: "github-dark",
    mode: "url",
  }),
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`Generation failed: ${response.status} ${await response.text()}`);
}

const result = await response.json();
const imageResponse = await fetch(result.data.imageUrl, {
  signal: AbortSignal.timeout(30_000),
});
if (!imageResponse.ok) {
  throw new Error(`Download failed: ${imageResponse.status}`);
}

await writeFile("build-report.png", Buffer.from(await imageResponse.arrayBuffer()));
console.log("Saved build-report.png");

Num serviço web, só deve concluir a tarefa depois do envio permanente terminar. Guardar apenas o URL temporário da API sem copiar o ficheiro cria uma falha adiada quando esse URL expirar.

Em modo URL, Python segue o mesmo padrão de dois pedidos: criar a renderização e descarregar o resultado. Timeouts explícitos impedem um worker de ficar bloqueado indefinidamente.

import os
from pathlib import Path

import requests

token = os.environ["MARKDOWN_TO_IMAGE_API_TOKEN"]
payload = {
    "markdown": "# Build report\n\n- Tests: **passed**\n- Deploy: **ready**",
    "format": "png",
    "width": 1200,
    "quality": 2,
    "theme": "github-dark",
    "mode": "url",
}

response = requests.post(
    "https://markdowntoimage.com/api/v1/images/generate",
    headers={"Authorization": f"Bearer {token}"},
    json=payload,
    timeout=30,
)
response.raise_for_status()

image_url = response.json()["data"]["imageUrl"]
image_response = requests.get(image_url, timeout=30)
image_response.raise_for_status()
Path("build-report.png").write_bytes(image_response.content)
print("Saved build-report.png")

Quando o volume aumentar, execute esta função numa fila de tarefas e não dentro de um pedido longo do utilizador. A fila controla concorrência e repetições e permite registar o URL final de armazenamento.

No n8n, coloque um nó HTTP Request depois do nó que cria ou obtém o Markdown. Guarde o token em n8n Credentials em vez de o colar no JSON do fluxo.

Method: POST
URL: https://markdowntoimage.com/api/v1/images/generate
Authentication: Header Auth
Header name: Authorization
Header value: Bearer {{$credentials.markdownToImageToken}}
Send Body: JSON
Body:
{
  "markdown": "{{$json.content}}",
  "format": "png",
  "width": 1200,
  "quality": 2,
  "theme": "github-dark",
  "mode": "url"
}

Ligue um segundo HTTP Request para descarregar {{$json.data.imageUrl}}, ative a saída de ficheiro e envie depois o binário para S3, Google Drive, Directus, WordPress, Slack ou outro destino. Configure o ramo de erro para que falhas de autenticação ou quota não publiquem um registo vazio.

Escolha URL quando a plataforma lida bem com JSON e consegue fazer um segundo download. É conveniente para filas, webhooks e fluxos sem código, mas o URL é temporário; a documentação oficial indica atualmente 24 horas.

Escolha binary quando pretende transmitir uma única resposta diretamente para armazenamento. Evita o segundo pedido HTTP, mas o cliente tem de tratar corretamente conteúdo binário, Content-Type, extensão, limites de memória e limpeza de envios incompletos.

Em qualquer modo, guarde o recurso final em armazenamento controlado por si. Registe também formato, largura, tema, ID do conteúdo, data de geração e hash do Markdown para facilitar deduplicação e diagnóstico.

A API documenta estes resultados importantes:

As repetições automáticas devem visar falhas transitórias, não todas as respostas fora de 200. Use backoff exponencial com jitter para 500 e timeouts de rede. Perante uma falha de ligação incerta, confirme se já existe uma saída para o mesmo hash antes de repetir, evitando várias renderizações pagas para uma única tarefa.

Registe estado, código do fornecedor, ID da tarefa, tentativa e latência, mas nunca o cabeçalho Authorization completo.

Antes de enviar tráfego real, confirme:

• token guardado num cofre cifrado do servidor;
• timeouts de ligação e totais configurados;
• repetições limitadas com backoff exponencial e jitter;
• concorrência compatível com quota e armazenamento seguinte;
• tamanho e campos obrigatórios do Markdown validados;
• formato, largura, tema, estilo de código e fonte fixados;
• resultados URL descarregados imediatamente para armazenamento permanente;
• nomes de ficheiro seguros e determinísticos;
• imagens publicadas com texto alternativo e contexto útil;
• utilização medida e alerta antes de esgotar a quota;
• fontes multilingues, linhas longas, tabelas, Mermaid e KaTeX testados com conteúdo real;
• alternativa manual para publicações críticas.

Comece com um conjunto pequeno e representativo. Dez exemplos reais de Markdown revelam mais problemas de layout do que centenas de pedidos “Hello World”.

Escolha um Markdown que o produto já produza e execute-o com o exemplo cURL. Verifique quebras de código, tabelas, fontes e dimensões antes de expandir o fluxo.

Quando a primeira renderização estiver correta, abra o guia da API do MarkdownToImage, crie um token exclusivo do servidor e leve a receita de Node.js, Python ou n8n para um pequeno teste de produção. Comece com um tipo de conteúdo real, um preset visual fixo, armazenamento permanente e erros observáveis; só depois aumente a escala com base nos resultados.