---
title: "Blog Hero Image API: Auto-Generate Featured Images"
description: "Auto-generate post hero artwork with the Blog Hero Image API. Send title, category, and optional photo URL as JSON, get a 1600x900 PNG for the article page."
url: "https://html2img.com/templates/blog-hero/"
---

# Blog Featured Hero: Blog Hero Image Generator API

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.

## At a glance

- **Template slug:** `blog-hero`
- **Category:** content
- **Endpoint:** `POST https://app.html2img.com/api/v1/templates/blog-hero`
- **Authentication:** `X-API-Key` header
- **Cost:** one credit per render, PNG or PDF
- **Page:** https://html2img.com/templates/blog-hero/

## Fields

| Field | Type | Required | Example |
| --- | --- | --- | --- |
| `title` | string | Yes | The quiet rise of the small-team dev shop |
| `subtitle` | string | No | Why eight-person studios are quietly outperforming the unicorn class. |
| `category` | string | No | Industry |
| `read_time` | string | No | 7 min read |
| `author_name` | string | No | Adaeze Okafor |
| `author_role` | string | No | Editor at Northwind Weekly |
| `author_avatar_url` | url | No | https://i.pravatar.cc/160?img=49 |
| `background_image_url` | url | No | https://picsum.photos/seed/blog-hero/1600/900 |
| `background_color` | string | No | #0F172A |
| `accent_color` | string | No | #22D3EE |

## Defaults

| Field | Default |
| --- | --- |
| `width` | 1600 |
| `height` | 900 |

## Example request

```bash
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"}'
```

## In your language

### PHP

```php
<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/blog-hero', ['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']);

$url = $response->json('url');
```

### Node.js

```javascript
const response = await fetch('https://app.html2img.com/api/v1/templates/blog-hero', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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"
}),
});

const { url } = await response.json();
```

### Python

```python
import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/blog-hero',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'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'},
)

url = response.json()['url']
```

## What it is for

### WordPress sites generating featured images per post title

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.

### Static blogs generating heroes at build time

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.

### Newsletters needing a header per issue

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 show notes pages

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.

### Knowledge base articles needing visual structure

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.

## Output

- **Dimensions:** 1600x900
- **Colour space:** sRGB
- **Transparency:** Not supported
- **Typical file size:** 120 KB to 400 KB
- **Platform specification:** [16:9 widescreen for blog and CMS themes](https://wordpress.org/documentation/article/post-thumbnails/)

## Common mistakes

### Theme aspect ratios disagree across templates

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.

### Title length variance creates inconsistent visual weight

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.

### Low-contrast accents over photographic backgrounds

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.

## Questions

### 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".

## Preview

![Blog Featured Hero: Blog Hero Image Generator API example render](https://i.html2img.com/image-1777560105058-580517.png)

## Related templates

- [quote-card](https://html2img.com/templates/quote-card/)
- [podcast-episode-card](https://html2img.com/templates/podcast-episode-card/)
- [podcast-cover](https://html2img.com/templates/podcast-cover/)

## See also

- [Every template](https://html2img.com/templates/)
- [Templates API reference](https://html2img.com/docs/templates/)
- [OpenAPI specification](https://html2img.com/openapi.json)