docs / generate

Generation API

base /generate/v121 endpoints

post/generate/v1/pdf_render4 credits

Render a PDF from inline HTML/CSS (Jinja2) or a built-in template_name + data (invoice/receipt/certificate/report). WeasyPrint, fonts pinned, network-off. Output: inline base64 (≤8MB) or one-time download token.

Parameter		Allowed / range	Description
html	optional	—	Inline HTML/CSS document (Jinja2 syntax allowed; rendered in a SANDBOXED env — no code execution). Mutually exclusive with template_name.
template_name	optional	invoice · receipt · certificate · report	Built-in PDF template (stateless — lives in engine, not stored). Supply `data` matching its contract (see template_list).
data	optional	—	Template variables (JSON object) — merged into the template. For built-ins see each template's data_contract.
paper	optional	A4 · A4 landscape · Letter · Letter landscape · A5 · Legal	Page size override for built-in templates.
filename	optional	—	Suggested download filename.
allow_hosts	optional	—	Comma-separated https hosts whose images/CSS the PDF may fetch (default NONE = network-off, SSRF-safe). Use data: URIs to embed assets without this.

Try in playground →

post/generate/v1/pdf_from_html4 credits

Shortcut for rendering inline HTML directly to PDF — the same WeasyPrint engine as pdf_render; `html` is required.

Parameter		Allowed / range	Description
html	required	—	HTML/CSS document to render (Jinja2 allowed, sandboxed).
data	optional	—	Optional Jinja2 variables for the HTML.
paper	optional	A4 · A4 landscape · Letter · A5 · Legal	Page size (only if your CSS uses {{ paper }}).
filename	optional	—	Suggested filename.
allow_hosts	optional	—	Allowlisted https hosts for remote assets (default none).

Try in playground →

post/generate/v1/pdf_from_url4 credits

Render a built-in or inline template to PDF, populating it with data fetched live from a JSON URL you supply. Useful when your invoice or report data lives at a public API endpoint — no manual copy-paste needed.

Parameter		Allowed / range	Description
data_url	required	—	https URL returning a JSON object used as template `data`.
template_name	optional	invoice · receipt · certificate · report	Built-in template to fill.
html	optional	—	Inline HTML template (instead of template_name).
data_path	optional	—	Optional dotted path into the fetched JSON to use as data (e.g. 'result.invoice').
paper	optional	A4 · A4 landscape · Letter · A5 · Legal	Page size override.
filename	optional	—	Suggested filename.

Try in playground →

post/generate/v1/og_image2 credits

Render a social / Open Graph card image (1200×630 default) from a built-in template or an inline layout spec. Supports automatic text-wrap and font scaling for long titles, colour gradients and badge overlays.

Parameter		Allowed / range	Description
template_name = og_basic	optional	og_basic · og_article · og_quote · og_product	Built-in card layout. See template_list for each layout's vars.
vars	optional	—	Card content (JSON): title/subtitle/badge/quote/author/site/name/tagline/cta + colors bg/bg2/fg/accent (hex).
layout	optional	—	Inline layout override (JSON) — {size:[w,h], ...} for a fully custom card without a built-in template.
width = 1200	optional	200–4000	Canvas width px.
height = 630	optional	200–4000	Canvas height px.
format = png	optional	png · jpeg · webp	Output image format.
filename	optional	—	Suggested filename.

Try in playground →

post/generate/v1/image_from_template2 credits

Alias of og_image (explicit Bannerbear 'create image from template' naming). template_name + vars → PNG.

Parameter		Allowed / range	Description
template_name	required	og_basic · og_article · og_quote · og_product	Built-in image template.
vars	optional	—	Template variables (see template_list).
width = 1200	optional	200–4000	Canvas width px.
height = 630	optional	200–4000	Canvas height px.
format = png	optional	png · jpeg · webp	Output format.
filename	optional	—	Suggested filename.

Try in playground →

post/generate/v1/image_from_url2 credits

Render an image template with `vars` fetched from a JSON URL (proxy, SSRF-validated). Data-driven banner generation.

Parameter		Allowed / range	Description
data_url	required	—	https URL returning a JSON object used as card `vars`.
template_name = og_basic	optional	og_basic · og_article · og_quote · og_product	Built-in template.
layout	optional	—	Inline layout override (JSON).
data_path	optional	—	Dotted path into the JSON to use as vars.
width = 1200	optional	200–4000	Canvas width px.
height = 630	optional	200–4000	Canvas height px.
format = png	optional	png · jpeg · webp	Output format.
filename	optional	—	Suggested filename.

Try in playground →

post/generate/v1/chart1 credit

Render a chart from a Chart.js-style spec — returns a PNG or SVG image. Supported chart types: bar, horizontal_bar, line, area, pie, doughnut, scatter and radar. Powered by a matplotlib backend.

Parameter		Allowed / range	Description
spec	required	—	Chart spec: {type, data:{labels:[...], datasets:[{label, data:[...], color?}]}, options:{title, x_label, y_label, width, height, legend}}.
format = png	optional	png · svg	Output format.
filename	optional	—	Suggested filename.

Try in playground →

post/generate/v1/chart_typesfree

List all supported chart types with a description of each. No input required.

Try in playground →

post/generate/v1/batch_pdf4 credits

Render up to 20 PDFs in one call. `jobs` = array of pdf_render param objects.

Parameter		Allowed / range	Description
jobs	required	—	Array of ≤20 pdf_render param objects ({html\|template_name, data, ...}).

Try in playground →

post/generate/v1/batch_image2 credits

Render up to 20 images in one call. `jobs` = array of og_image param objects.

Parameter		Allowed / range	Description
jobs	required	—	Array of ≤20 og_image param objects ({template_name\|layout, vars, ...}).

Try in playground →

post/generate/v1/template_listfree

List built-in templates (PDF + image) with their data contracts. Stateless — there is NO stored-template management (create/upload/delete out of scope).

Try in playground →

post/generate/v1/validate_htmlfree

Lint HTML/CSS for the PDF path WITHOUT rendering: flags remote resources that the SSRF-safe renderer will block, size, and tag-balance hints. Deterministic.

Parameter		Allowed / range	Description
html	required	—	HTML document to lint.

Try in playground →

post/generate/v1/healthfree

Renderer diagnostics — which backends (WeasyPrint/Pillow/matplotlib) are loadable and their versions. No input.

Try in playground →

post/generate/v1/qr1 credit

Generate a QR code (PNG or SVG) with custom fg/bg color, error-correction, and an OPTIONAL center logo fetched from logo_url (SSRF-guarded, via proxy). Use error_correction=h when embedding a logo so it stays scannable.

Parameter		Allowed / range	Description
data	required	—	The content to encode: a URL, text, vCard string, etc.
format = png	optional	png · svg	Output image format. png supports logo-embed + colors; svg is scalable (logo-embed requires png).
error_correction = m	optional	l · m · q · h	Recovery level: l~7% · m~15% · q~25% · h~30%. Use h with a logo.
scale = 8	optional	1–40	Module size in pixels.
border = 4	optional	0–20	Quiet-zone width in modules (spec default 4).
color	optional	—	Foreground (dark) color: #rrggbb / #rgb / basic CSS name.
background	optional	—	Background color, or 'transparent'.
logo_url	optional	—	URL of a logo to embed in the center (PNG output only). Fetched through the proxy with a full SSRF guard.
logo_size = 0.22	optional	0.05–0.3	Logo size as a fraction of the QR side (0.05–0.30; >0.25 risks unscannable codes even at EC-H).

Try in playground →

post/generate/v1/barcode1 credit

Generate a 1D barcode IMAGE (PNG or SVG) from data: EAN-13/8, UPC-A, Code-128, Code-39, ISBN-10/13, ITF, GS1-128, JAN, PZN, Codabar. Check digits are validated — a wrong EAN/UPC/ISBN check digit returns a structured error, not a silent fix.

Parameter		Allowed / range	Description
data	required	—	The value to encode. For EAN/UPC supply the digits; the check digit is computed (or validated if you include it).
type	required	ean13 · ean8 · ean14 · upca · code128 · code39 · isbn13 · isbn10 · issn · itf · gs1_128 · jan · pzn · codabar	Barcode symbology.
format = png	optional	png · svg	Output image format.
show_text = true	optional	—	Print the human-readable value under the bars.
module_height = 15	optional	2–100	Bar height in mm.
color	optional	—	Bar color (#rrggbb / name).
background	optional	—	Background color (#rrggbb / name).

Try in playground →

post/generate/v1/code_image2 credits

Render a syntax-highlighted code snippet as a PNG with a carbon/ray.so-style window frame. 500+ languages (Pygments), 40+ themes, optional line numbers.

Parameter		Allowed / range	Description
code	required	—	The source code to render.
language	optional	—	Language for highlighting (python, javascript, go, rust, sql…). Omit to auto-detect.
theme = monokai	optional	abap · algol · algol_nu · arduino · autumn · borland · bw · coffee · colorful · default · dracula · emacs · friendly · friendly_grayscale · fruity · github-dark · gruvbox-dark · gruvbox-light · igor · inkpot · lightbulb · lilypond · lovelace · manni · material · monokai · murphy · native · nord · nord-darker · one-dark · paraiso-dark · paraiso-light · pastie · perldoc · rainbow_dash · rrt · sas · solarized-dark · solarized-light · staroffice · stata-dark · stata-light · tango · trac · vim · vs · xcode · zenburn	Color theme (Pygments style).
window_style = dark	optional	dark · darker · light · none	Frame: dark/darker/light window chrome with traffic-light dots, or 'none' for a bare image.
line_numbers = false	optional	—	Show line numbers in the gutter.
font_size = 20	optional	10–48	Font size in px.

Try in playground →

post/generate/v1/favicon2 credits

Turn one source image into a complete favicon bundle: multi-resolution favicon.ico, a named PNG set (16→512 incl. apple-touch-icon + android-chrome), site.webmanifest, and the ready-to-paste <head> <link> snippet. Source from image_url (SSRF-guarded) or a base64 upload.

Parameter		Allowed / range	Description
image_url	optional	—	URL of the source image (PNG/JPG/etc). Fetched through the proxy with a full SSRF guard. Provide this OR image_base64.
image_base64	optional	—	Base64-encoded source image (data-URI prefix accepted). Use instead of image_url for direct uploads.

Try in playground →

post/generate/v1/vcard1 credit

Build a vCard (.vcf) contact file from contact fields (vCard 3.0 or 4.0). Returns the raw.vcf text + a base64 data-URI you can download or encode into a QR.

Parameter		Allowed / range	Description
full_name	optional	—	Full display name (or supply first_name/last_name).
first_name	optional	—	Given name.
last_name	optional	—	Family name.
organization	optional	—	Company/organization.
title	optional	—	Job title.
phone	optional	—	Phone number(s) — string or array.
email	optional	—	Email address(es) — string or array.
url	optional	—	Website URL(s) — string or array.
address	optional	—	Postal address (single line).
note	optional	—	Free-text note.
birthday	optional	—	Birthday (YYYY-MM-DD).
version = 3.0	optional	3.0 · 4.0	vCard spec version (3.0 = widest compatibility, 4.0 = modern).
as_qr = false	optional	—	Also return a scannable PNG QR of the vCard (add-to-contacts).

Try in playground →

post/generate/v1/ical1 credit

Build an iCalendar (.ics) event file from event fields (RFC 5545). Supports timed or all-day events, end-time or duration, location, description, organizer. Returns the raw.ics + a base64 data-URI.

Parameter		Allowed / range	Description
summary	required	—	Event title.
start	required	—	Start: ISO-8601 (2026-07-01T15:00:00+00:00) or YYYY-MM-DD (all-day).
end	optional	—	End time (ISO-8601 or YYYY-MM-DD). Omit to use duration_minutes.
duration_minutes = 0	optional	0–100000	Event length in minutes (used when `end` is absent).
location	optional	—	Event location.
description	optional	—	Event details.
url	optional	—	Event URL.
organizer_email	optional	—	Organizer email.
uid	optional	—	Stable UID (auto-generated if omitted).
as_qr = false	optional	—	Also return a scannable PNG QR of the event.

Try in playground →

post/generate/v1/wifi1 credit

Generate a WiFi-join QR code (PNG/SVG) from network credentials — scan to connect, no typing. Encodes the standard WIFI: payload (WPA/WEP/open, hidden networks).

Parameter		Allowed / range	Description
ssid	required	—	Network name (SSID).
password	optional	—	Network password (required unless encryption=nopass).
encryption = WPA	optional	WPA · WEP · nopass	Security type: WPA (incl. WPA2/WPA3), WEP, or nopass (open network).
hidden = false	optional	—	Mark the network as hidden (non-broadcast SSID).
format = png	optional	png · svg	Output image format.
scale = 8	optional	1–40	Module size in pixels.
error_correction = m	optional	l · m · q · h	QR recovery level.

Try in playground →

post/generate/v1/batch1 credit

Generate up to 50 small assets in one request. Items run independently — a bad item yields its own error entry, never fails the batch. NOTE: items that fetch a remote logo_url/image_url ARE supported and SSRF-guarded.

Parameter		Allowed / range	Description
items	required	—	Up to 50 items, each {action, params} where action is qr\|barcode\|code_image\|favicon\|vcard\|ical\|wifi.

Try in playground →

Example request · pdf_render

curl -X POST https://api.reefapi.com/generate/v1/pdf_render \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"template_name":"invoice","data":{"company":{"name":"Acme"},"items":[{"description":"Widget","qty":2,"unit_price":9.5}],"subtotal":19,"total":19}}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}