Skip to content

Rendering

BinderyPress renders templates into documents on demand. You send a template (or template ID) with data, and get back a rendered document in your chosen format.

Format Content-Type Description
pdf application/pdf Vector PDF. Best for printing and archival.
png image/png Raster image. Configurable DPI.
zpl text/plain Zebra Programming Language. For thermal label printers.
html text/html Rendered HTML. Useful for previews and web display.

Control how you receive the rendered output with the delivery field.

{ "delivery": "url" }

The response includes a url field pointing to the rendered output. The file is stored for 7 days and can be downloaded with your API key.

{
"id": "a1b2c3d4-...",
"status": "complete",
"format": "pdf",
"url": "https://api.binderypress.dev/v1/render-outputs/a1b2c3d4-...",
"sizeBytes": 12345,
"renderTimeMs": 450
}
{ "delivery": "inline" }

The rendered document is returned directly in the response body with the appropriate Content-Type header. No URL is provided; the rendered file is still kept for 7 days and then deleted, like every render output. A batch answers differently: see its inline delivery.

This is useful when you need the document immediately and don’t need to download it later.

For PNG and ZPL output, set the dpi field to control resolution, from 50 to 600. Default is 300 DPI for PNG and 203 DPI for ZPL (set it to your printer’s density).

{
"format": "png",
"dpi": 150
}

Higher DPI produces larger files but sharper output. PNG and ZPL output is limited to 80 megapixels, so a large page at a high DPI may need a lower one (see Limits). Common values:

DPI Use Case
72 Screen preview
150 Web display
300 Print quality (default)
600 High-quality print

Renders made with a test key (bp_sk_test_) produce watermarked output and are tagged as test renders. They do not count against your monthly quota.

Test renders are functionally identical to live renders — same templates, same formats, same processing pipeline. The only difference is the watermark and quota treatment.

When a render request arrives:

  1. Auth — API key or session is validated.
  2. Template resolution — Inline template is used directly, or the saved template is loaded from storage by templateId.
  3. Request checks — The template is validated, and the request is checked against the limits (DPI, page size, image size). A request that fails here is refused and not counted.
  4. Rate limit — Request is checked against the team’s rate limit.
  5. Quota — Monthly render count is checked (live mode only).
  6. Render — The template and data are sent to a container in the render pool. The container uses a headless browser to produce the output. If that container does not respond at all, the render is sent once more to the next container in the pool; it still counts as one render. A render that fails inside a container is not retried. A render that takes longer than 30 seconds (a batch: 60 seconds) is stopped with 504 RENDER_TIMEOUT.
  7. Storage — The output is written to cloud storage (URL delivery) or streamed back (inline delivery).
  8. Response — The render metadata or inline content is returned.

Render outputs (URL delivery) are stored for 7 days. After that, the file is deleted and the download URL returns 404.

Each render also leaves a record in your render history, visible in the dashboard:

After What happens
7 days The rendered file is deleted
30 days The request body you sent is deleted; the record keeps only basic details (job ID, template, format, status, timing)
90 days The record is deleted
Limit Value Error
DPI 50 to 600 400 DPI_OUT_OF_RANGE
Width and height (template size, media page and label) 1 to 1,500 mm each 400 SIZE_OUT_OF_RANGE
Total image size (PNG, ZPL) 80 megapixels 400 IMAGE_TOO_LARGE
Time per render 30 seconds 504 RENDER_TIMEOUT
Time per batch 60 seconds 504 RENDER_TIMEOUT
Items in a batch Dev 10, Small 100; Big and Enterprise 250 for PDF and HTML, 100 for ZPL and PNG 400 BATCH_TOO_LARGE
Text returned inline by a batch (ZPL, HTML) 10 MB in total 400 INLINE_TOO_LARGE
Request body size 10 MB max (1 MB for demo keys) 413 PAYLOAD_TOO_LARGE
Output retention 7 days —
Render history Request body 30 days, record 90 days —
Container pool size 3 instances —

A request outside the DPI, size or image limits is refused before anything is rendered and is not counted toward your rate limit or quota. See POST /v1/render for the error bodies.