html2media

API Reference

Base URL: https://api.html2media.com

Authentication

Render endpoints use the X-API-Key header with a key from your dashboard. Account endpoints (/me, /me/keys) use a Bearer JWT from Kinde — intended for the dashboard, not for API clients.

POST /images

Submit an HTML render job. Returns a job ID immediately (status 202).

Body

  • html (string, required) — the HTML to render.
  • css (string, default "") — extra CSS applied to the document.
  • width (int, default 1080) — viewport width in px.
  • height (int, default 1080) — viewport height in px.
  • format ("jpeg" | "png", default jpeg).
  • callback_url (string, optional) — webhook target for async delivery.

Response (202)

{"job_id":"abc-123","status":"queued"}

GET /images/{id}

Status + result for a render job (scoped to your API key).

# queued / processing
{"status":"queued","url":null,"error":null}

# done — url is the rendered image
{"status":"done","url":"https://.../result.png","error":null}

# failed
{"status":"failed","url":null,"error":"..."}

Webhook payload

When callback_url is set, html2media POSTs the final state (with retries: immediate, +30s, +5min) when the job reaches done or failed:

{"job_id":"abc-123","status":"done","url":"https://.../result.png","error":null}

GET /me

(Bearer JWT) Current user + list of active (non-revoked) API keys.

POST /me/keys

(Bearer JWT) Create a new API key.

# Request
{"label":"Production"}

# Response (201) — raw key shown ONCE
{"id":"...","label":"Production","key_prefix":"htm_a1b2c3d4","key":"htm_a1b2c3d4...","created_at":"..."}

DELETE /me/keys/{id}

(Bearer JWT) Soft-delete a key. Subsequent requests with it return 401.

Errors

  • 400 — invalid callback_url (not http(s) or resolves to a private address).
  • 401 — missing/invalid/revoked key, or bad JWT.
  • 403 — account pending approval (key creation gated during beta).
  • 404 — unknown job ID (or owned by another key).
  • 422 — malformed request body (e.g. missing html).