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.
Output Formats
Section titled “Output Formats”| 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. |
Delivery Modes
Section titled “Delivery Modes”Control how you receive the rendered output with the delivery field.
URL Delivery (default)
Section titled “URL Delivery (default)”{ "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}Inline Delivery
Section titled “Inline Delivery”{ "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.
DPI (PNG and ZPL)
Section titled “DPI (PNG and ZPL)”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 |
Test Mode
Section titled “Test Mode”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.
Rendering Pipeline
Section titled “Rendering Pipeline”When a render request arrives:
- Auth — API key or session is validated.
- Template resolution — Inline template is used directly, or the saved template is loaded from storage by
templateId. - 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.
- Rate limit — Request is checked against the team’s rate limit.
- Quota — Monthly render count is checked (live mode only).
- 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. - Storage — The output is written to cloud storage (URL delivery) or streamed back (inline delivery).
- Response — The render metadata or inline content is returned.
Render Job Retention
Section titled “Render Job Retention”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 |
Limits
Section titled “Limits”| 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.