A PixlDocs template is built one of two ways: by placing elements on a fixed page, or by writing HTML and CSS. Both render through the same API, on the same key, at the same price. This page is the rule for choosing, and it is the only rule — the create dialog and the MCP tools repeat it, they do not add to it.

The one-line rule

Is the finished artefact always the same size? If yes, build it on the canvas. If its length depends on the data — three line items today, ninety next month — write it in HTML.

Choose by artefact

Which substrate to use for each kind of artefact
Artefact	Build it as	Why
Invoice, receipt, statement	html	The line-item table decides the page count.
Payslip, payout statement	html	Rows per employee or per order vary every cycle.
Delivery note, purchase order	html	Same reason: a table of unknown length.
Report, contract	html	Flowing prose with running headers and page numbers.
Certificate, diploma	canvas	One sheet, laid out by eye, never longer.
Ticket, badge, ID card	canvas	Fixed physical size; a second page would be wrong.
Gift card, label	canvas	Fixed rectangle, print-positioned.
Social image, OG image, ad variant	canvas	Fixed pixel size, design-led, exported as PNG or WebP.

A certificate is a document, and it is still canvas

The split is not documents-versus-images. It is fixed-size versus flowing. A certificate, a ticket and an ID card are all documents you would print, and all three belong on the canvas, because their whole design assumes one sheet of a known size. Conversely a long HTML template can be exported as a PNG. Choose on length, not on file type.

What each one gives you

Canvas

Drag, snap and align on a page of a size you pick — A4, a ticket, 1080×1080.
Smart elements: QR codes, avatars, badges, ratings, tables.
Per-element overflow policy, so a long name shrinks instead of breaking the design — see overflow & pagination in the editor.
Themes, and animation with MP4 export from the editor.
PNG and WebP output at up to 4×, which is what an image pipeline needs.

HTML

Your own markup and CSS, with Liquid for data, loops and arithmetic.
Content longer than one page continues onto the next automatically.
Running headers and footers, repeated table headings, real page numbers.
Paste a document you already generate and get a bound template back.
Faster: on staging, an HTML PDF renders in roughly 0.8s at the median against roughly 3.8s for a canvas PNG.

What is the same either way

One endpoint. POST /v1/render takes a template_id and your data, whatever the template is made of.
One field contract. Both kinds publish the keys they accept via the templates endpoint, and both refuse a key they do not declare.
One price. Credits are charged per page and resolution, never by substrate — see pricing.
One account, one key, one usage ledger, one MCP server.

kind is ours, not yours

Templates report a kind of canvas or html so you can see what you are looking at. Your render call never has to branch on it. If you ever find yourself writing if (kind === 'html') in integration code, that is our bug — tell us.

Creating one of each

In the app, Create template asks how you want to build it and states the rule above in one line. Over MCP, the tool you call is the choice:

text

create_template          → canvas, fixed size
create_html_template     → HTML, flows onto more pages
generate_html_template   → describe it in words, get an HTML template
import_html_template     → paste the document you already send

There is no conversion between the two, and there deliberately is not one: a fixed design and a flowing document disagree about what should happen when the content grows, so a converted template would be wrong in exactly the case you built it for. Pick with the rule at the top, and if the artefact genuinely has both a fixed face and a flowing back — a badge with an itinerary, say — build two templates and call the API twice.