Templates API Reference

Templates are pre-built image designs hosted on html2img. POST a JSON payload to a named template endpoint and receive a rendered PNG, or a PDF if you ask for one. Templates are versioned and tested, so the rendered output is stable.

For sample renders, use cases and the marketing-side overview, see the templates gallery. This page is the API reference.

How templates differ from HTML and screenshot requests

The /api/v1/html and /api/v1/screenshot endpoints render whatever markup or web page you point them at. Templates skip the markup step. The design lives on our side, you supply only the data, and the API returns a finished image. This makes integration shorter and the output more predictable.

Authentication

Every template request requires the X-API-Key header. The authentication docs cover where to get a key and how to keep it secure.

Rate limits

Template requests count against the same monthly credit pool as HTML and screenshot requests. The quick start guide explains how credits work and how to monitor usage.

Request shape

All template requests follow the same shape:

POST https://app.html2img.com/api/v1/templates/{slug}
X-API-Key: <your-api-key>
Content-Type: application/json

{
 "input_one": "value",
 "input_two": 42
}

The path slug picks the template. The JSON body contains the inputs that template accepts. Output is PNG by default, served from our CDN.

Output format

Alongside the template's own inputs, every template accepts an optional format parameter in the JSON body. It defaults to png; set it to pdf to receive a PDF document instead:

{
 "input_one": "value",
 "input_two": 42,
 "format": "pdf"
}

With format: "pdf" the response url points to a .pdf file instead of a .png. PDF output is vector, with selectable text and embedded fonts, and costs the same single credit as a PNG render. The format parameter docs cover PDF output behaviour in detail. Document-shaped templates like invoices, receipts, certificates and tickets are the natural fit.

Response shape

A successful render returns a JSON envelope:

{
 "success": true,
 "id": "abc123",
 "url": "https://i.html2img.com/abc123.png",
 "credits_remaining": 1234,
 "template": "open-graph-image"
}

The same response shape used everywhere else in the API. See the API parameters reference for shared rendering options like DPI.

Available templates

Templates are listed below by category. Each links to a full reference page covering inputs, defaults, code examples and errors. New templates appear here automatically as they are added to the API.

business

• Invoice Image - Render full invoices as PNG images or A4 PDFs for emails, dashboards, and exports (View marketing page)
• Event Ticket - Print- and email-ready tickets with QR/barcode slot and perforated stub (View marketing page)
• Receipt Image - Compact order receipts as PNGs for confirmation emails or PDFs for expense filing (View marketing page)
• Product Card - E-commerce product cards with price, optional sale price, and CTA (View marketing page)
• Business Card - Digital and print-ready business cards in three layout variants (View marketing page)
• Coupon Voucher - Promotional voucher images sized for email body and SMS preview (View marketing page)
• Certificate of Completion - Print-ready certificates for course completion, training, and recognition (View marketing page)

content

• Quote Card - Pull-quote cards for testimonials, reviews, and shareable quotes (View marketing page)
• Podcast Episode Card - Per-episode share cards sized for Twitter, LinkedIn, and Slack unfurls (View marketing page)
• Podcast Cover - Square cover artwork sized for Apple Podcasts, Spotify, and the major directories (View marketing page)
• Email Header - Wide email banner artwork sized for newsletter and transactional templates (View marketing page)
• Blog Featured Hero - Editorial hero images for blog posts and article pages (View marketing page)

developer

• GitHub Social Preview - Repo cards sized for GitHub social preview, share posts, and READMEs (View marketing page)
• Project Showcase - "We shipped X" hero cards for changelogs and launch announcements (View marketing page)
• Code Screenshot - Beautiful syntax-highlighted code screenshots with window chrome (View marketing page)

real-estate

• Real Estate Listing - Property listing cards for MLS exports, social shares, and email blasts (View marketing page)

social

• Instagram Square Post - Bold square images sized for the Instagram feed (View marketing page)
• Open Graph Image - Generate dynamic Open Graph images from JSON (View marketing page)
• Twitter/X Post Image - Generate share-ready images sized for Twitter/X posts (View marketing page)
• YouTube Thumbnail - High-contrast 16:9 thumbnails optimized for click-through (View marketing page)
• Facebook Post Image - Bold share images sized for Facebook feed posts (View marketing page)
• LinkedIn Post Image - Polished share images sized for LinkedIn feed posts (View marketing page)
• Pinterest Pin - Vertical 2:3 pins with strong typography that stand out in feed (View marketing page)
• Tweet Mockup Card - Render a tweet-style card from supplied data — avatar, body, image, metrics (View marketing page)
• Instagram Story - Vertical 9:16 covers for Instagram and TikTok stories (View marketing page)

Errors

Templates use the standard HTML to Image error envelope. Validation failures return 422 with field-level details, unknown slugs return 404, missing or invalid keys return 401, and rate-limit hits return 429. The testing and debugging guide covers how to reproduce and inspect these locally.

Looking for the marketing-side overview, with sample renders and use cases? See the templates gallery.