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.

Feature	v1 (Chromium)	v2 (WeasyPrint)
RGB PDF	Yes	Yes
CMYK (DeviceCMYK)	No	Yes
ICC Profiles	No	Yes
PDF/X-4 (Print Standard)	No	Yes
Bleed / Trim Marks	No	Yes
CSS @page (full)	Partial	Complete
Fallback	—	Chromium (auto)

Endpoint

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

Request Body

Field	Type	Default	Description
html	string	—	Self-contained HTML with inline CSS (required)
format	string	"A4"	A4, A3, A5, Letter, Legal, Tabloid
landscape	boolean	false	Landscape orientation
margin	object	{}	Page margins: `{top, right, bottom, left}` in CSS units
print_background	boolean	true	Render CSS backgrounds
color_mode	string	"rgb"	`"rgb"` or `"cmyk"` — CMYK uses DeviceCMYK colors
icc_profile	string	null	ICC profile: `"iso-coated-v2-300"`, `"fogra39"`, `"srgb"`
bleed	string	"0mm"	Bleed area, e.g. `"3mm"` for print
trim_marks	boolean	false	Add crop and cross marks
pdf_version	string	"auto"	`"auto"`, `"1.7"`, or `"x-4"` (PDF/X-4 for print production)

Examples

Simple RGB PDF

curl -X POST https://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://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://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

Value	Profile	Use Case
iso-coated-v2-300	ISO Coated v2 300%	European offset printing (standard)
fogra39	Fogra 39L	European offset, older standard
srgb	sRGB IEC61966-2.1	Screen/digital output

Fallback Behavior

If WeasyPrint fails (e.g. unsupported CSS), the endpoint automatically falls back to the Chromium engine (same as /render/pdf). The response header X-PDF-Engine: chromium-fallback indicates when this happens.

Error Responses

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

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

← Back to API Docs