---
title: "HTML → a fixed-size image"
method: POST
path: "/api/render/image"
tags: ["Rendering"]
---

# HTML → a fixed-size image

`POST /api/render/image`

## Request

- Base URL: `https://snaplab.dev`
- URL: `https://snaplab.dev/api/render/image`
- Auth: HTTP bearer

Paint HTML (or a `{{ template }}` + `data`) onto an exact width×height canvas. Defaults to 1200×630 @2x — an Open Graph card.

## Request body

- ImageOptions: Fixed-canvas rendering for social/OG cards. Requires `html` or `template`.
  - `html` string
  - `template` string: HTML with `{{ placeholders }}`, substituted from `data` and HTML-escaped.
  - `data` object
  - `css` string
  - `width` integer
  - `height` integer
  - `deviceScaleFactor` number
  - `format` 'png' | 'jpeg' | 'webp'
  - `quality` integer
  - `googleFonts` string
  - `darkMode` union: `true`/`"force"` darken the card even without a dark theme; `"prefers"` is the media query only.
    - boolean
    - 'prefers' | 'force'
  - `delayMs` integer
  - `cache` boolean
  - `responseType` 'binary' | 'json'

## Response `200`

The rendered card.

- HostedRender: Answer for `responseType: "json"` — the render is stored and served from a public, immutable URL.
  - `url` string, uri, required
  - `id` string, required
  - `format` string, required
  - `width` integer
  - `height` integer
  - `bytes` integer, required
  - `cacheHit` boolean
  - `durationMs` integer

## Other responses

- `400`: Invalid options, or a target that resolves to a private/blocked address.
- `401`: Missing or invalid API key / signature.
- `402`: Subscription past due (`payment_required`).
- `422`: The render can never succeed as written (`selector_not_found`).
- `429`: Rate limit or monthly quota exceeded (`quota_exceeded`).
- `502`: The target site was unreachable (`upstream`).
- `503`: Queue saturated or browsers not ready. Retry after `Retry-After` seconds.
- `504`: The page did not finish in time (`timeout`).

---

[API](https://skmtc.dev/snaplab/apis/snaplab-api.md) · [All operations](https://skmtc.dev/snaplab/apis/snaplab-api/llms.txt) · [OpenAPI document](https://skmtc.dev/snaplab/apis/snaplab-api/revisions/4dbfbd8cd118?raw)