PDF v2

PDF Rendering with WeasyPrint

Print-ready PDFs with CMYK, ICC profiles, bleed, trim marks, and PDF/X-4 support.

Overview

The /render/pdfv2 endpoint uses WeasyPrint instead of Chromium for PDF generation. This provides full CSS Paged Media support and professional print features that Chromium cannot offer.

Endpoint

POST https://www.supaserv.io/render/pdfv2
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

Examples

Simple RGB PDF

curl -X POST https://www.supaserv.io/render/pdfv2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello PDF v2</h1><p>Rendered with WeasyPrint</p>",
    "format": "A4"
  }' \
  --output simple.pdf

Print-Ready CMYK with Bleed

curl -X POST https://www.supaserv.io/render/pdfv2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"background:#000;color:#fff;padding:40px\"><h1>Print Flyer</h1></div>",
    "format": "A4",
    "color_mode": "cmyk",
    "icc_profile": "iso-coated-v2-300",
    "bleed": "3mm",
    "trim_marks": true,
    "pdf_version": "x-4"
  }' \
  --output flyer-cmyk.pdf

Landscape with Custom Margins

curl -X POST https://www.supaserv.io/render/pdfv2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<table>...</table>",
    "format": "A3",
    "landscape": true,
    "margin": {"top": "15mm", "right": "20mm", "bottom": "15mm", "left": "20mm"}
  }' \
  --output report-landscape.pdf

HTML Guidelines

WeasyPrint uses its own rendering engine (not a browser). Keep these in mind:

• Self-contained HTML: Inline all CSS. External stylesheets may not load.
• No JavaScript: WeasyPrint does not execute JS. Use pre-rendered HTML.
• Fonts: Use @font-face with URLs or base64-encoded fonts. System fonts (Liberation, DejaVu) are available.
• Multi-page: Use page-break-before: always for page breaks.
• @page rules: CSS @page rules are fully supported and respected.

CMYK & Print Production

When color_mode: "cmyk" is set, WeasyPrint outputs DeviceCMYK colors in the PDF. For professional print:

• Set pdf_version: "x-4" for PDF/X-4 compliance
• Choose an ICC profile matching your printer (e.g. "iso-coated-v2-300" for European offset)
• Add bleed: "3mm" for standard print bleed
• Enable trim_marks: true for crop marks

For screen/digital PDFs (reports, invoices), color_mode: "rgb" (default) is sufficient.

ICC Profiles

Fallback Behavior

If WeasyPrint fails (e.g. unsupported CSS), the endpoint automatically falls back to the Chromium engine (same as /render/pdf). Every response names its engine in X-PDF-Engine: weasyprint or chromium-fallback. On a fallback, X-PDF-Fallback-Reason carries the cause (sidecar_disabled, sidecar_down, sidecar_http:500, sidecar_error:<code> or render_error) and X-PDF-Fallback-Detail the message. A CMYK job that comes back as chromium-fallback is RGB, so check the header.

Error Responses

// 400: missing HTML
{ "error": "html is required (string)" }

// 500: both engines failed
{ "error": "PDF failed (both engines): ..." }