Send the post title and metadata as JSON, get back a 1600x900 PNG sized for blog and CMS heroes.
Editorial sites and static-site generators use the Blog Hero Image API to skip the per-post design step that turns a small writing team into a bottleneck. The 1600x900 widescreen ratio fits modern blog themes and renders cleanly in WordPress, Astro, Hugo, and Eleventy without re-cropping. You post the title, category badge, optional author block, and an optional background photo URL, and the response holds a PNG ready to set as the post's featured image.
curl -X POST https://app.html2img.com/api/v1/templates/blog-hero \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"The quiet rise of the small-team dev shop","subtitle":"Why eight-person studios are quietly outperforming the unicorn class.","category":"Industry","read_time":"7 min read","author_name":"Adaeze Okafor","author_role":"Editor at Northwind Weekly","author_avatar_url":"https://i.pravatar.cc/160?img=49","background_image_url":"https://picsum.photos/seed/blog-hero/1600/900","background_color":"#0F172A","accent_color":"#22D3EE"}'
A single cURL call to render a Blog Featured Hero as a PNG. Add "format": "pdf" to the payload to get a PDF instead. For the full PHP, Node and Python equivalents, plus every input the template accepts, see the
Blog Featured Hero API reference.
Setting up your key is covered in the
authentication guide.
View the Blog Featured Hero API reference: inputs, defaults, error responses and cURL, PHP, Node and Python code samples. Read the docs.
WordPress publishers with 12 contributors hate scheduling design time for every post. Hook the publishing flow into a webhook, post the title and category to the Blog Hero Image API, and store the returned URL on the featured-image meta field. New posts go live with consistent artwork, and editors stop blocking each other on a shared design queue. Northwind Weekly ships 26 posts a week through this flow with no designer in the loop.
Astro, Hugo, and Eleventy sites can call the endpoint during the build step and cache the resulting URLs in the build output. The site rebuilds when the content changes, the new heroes are generated only when the post title or metadata shifts, and visitors get fresh artwork without runtime calls. Riverside Bakery's recipe blog runs this pattern and saves 35 minutes per release on hand-cropped photos.
Editors who ship a weekly issue benefit from a fresh hero that reads as continuous with the previous week. Render the issue title and date, place the cached URL in the email template, and the asset embeds reliably across Gmail, Outlook, and Apple Mail. Wren Analytics produces a Tuesday digest with a hero card that takes 8 seconds to generate during the publishing pipeline.
Podcast websites that publish show notes per episode use a hero image to anchor each page. Render the episode title with the host avatar and a category tag, embed the result above the show notes, and the page reads as a polished editorial piece rather than a transcript dump. The image also doubles as the og:image for that page when paired with the open-graph-image template for the share variant.
Long-form support docs benefit from a hero that telegraphs the topic before the reader scrolls. Render the article title with a category badge ("Billing", "Integrations", "Troubleshooting") and embed at the top of the doc page. Halberd Software's help center uses this pattern across 240 articles, and the bounce rate on long pages drops because readers see they have landed on the right thing.
Matches the spec at 16:9 widescreen for blog and CMS themes.
These specifications describe the default PNG output. The template can also return a PDF document with selectable text through the HTML to PDF API: set format to pdf in the request. See the format parameter docs for how PDF output behaves.
POST to the template endpoint with the values you want rendered. Authenticate with your API key.
The template is rendered server-side as a 1600x900 PNG, or as a PDF document if you set format to pdf.
Cache it, embed it in your page, attach it to an email.
Some themes crop heroes to 1.91:1 for sharing while displaying 16:9 on the post page itself. Test your theme's archive view and OG behavior, and switch to the open-graph-image template for the share variant if your theme expects a different aspect ratio.
Short titles render bold while long titles shrink, and the index page ends up looking lopsided across rows. Standardize on a title length range (40 to 80 characters) in your editorial guidelines so the index reads as a coherent grid.
A pastel accent color over a busy hero photo disappears against the image. Either pass an accent_color with a contrast ratio above 4.5 against the typical photo, or use a solid background_color rather than a photographic background.
A quick summary of what the Blog Featured Hero template accepts. The full reference, with example values and array shapes, is in the docs.
| Name | Type | Required |
|---|---|---|
title | string | Required |
subtitle | string | Optional |
category | string | Optional |
read_time | string | Optional |
author_name | string | Optional |
author_role | string | Optional |
author_avatar_url | url | Optional |
background_image_url | url | Optional |
background_color | string | Optional |
accent_color | string | Optional |
See the full inputs reference for descriptions, examples and validation rules.
Other templates in the content and marketing category.
Beautiful syntax-highlighted code screenshots with window chrome
Wide email banner artwork sized for newsletter and transactional templates
Repo cards sized for GitHub social preview, share posts, and READMEs
Generate dynamic Open Graph images from JSON
Square cover artwork sized for Apple Podcasts, Spotify, and the major directories
Per-episode share cards sized for Twitter, LinkedIn, and Slack unfurls
E-commerce product cards with price, optional sale price, and CTA
"We shipped X" hero cards for changelogs and launch announcements
Pull-quote cards for testimonials, reviews, and shareable quotes
A starting point from each of the other two template categories.
See the full template gallery for every design grouped by category.
What size suits most blog themes?
The 1600x900 (16:9) output covers WordPress, Astro, Hugo, Eleventy, and Ghost defaults. If your theme expects 1.91:1 for share previews, render once with this template for the on-page hero and once with open-graph-image for the share variant.
Can I overlay a photo?
Yes, pass background_image_url with a public URL. The renderer applies a subtle darkening overlay so the title stays readable on top of the photo. For a flat-color background, leave the field empty and pass background_color instead.
How do I match my brand?
Set accent_color and font_pair_id (default, serif, mono) to align with your editorial style guide. The accent applies to the category badge and underline, while the font choice runs through the title and author block.
Will it work for static site generators?
Yes, call the endpoint during the build step and cache the URL in the build output. The Astro, Hugo, and Eleventy ecosystems all support build-time HTTP calls through their data-loading APIs. Most teams cache by content hash so renders only run when the source content changes.
Does the title automatically wrap?
Yes, the renderer scales the type down to fit longer titles and wraps at word boundaries. Titles up to 90 characters render comfortably. Test with your worst-case headline length so you know how the layout behaves under stress.
Can I add a category badge?
Yes, pass category with a string up to 24 characters. The badge renders in the accent_color and sits above the title. Use this slot for editorial sections like "Industry", "Tutorial", or "Opinion".
25 renders a month on the free tier. See the pricing page for higher-volume plans.