OG Image

API key v1

Generate a social-card image from a title, subtitle and logo.

Renders an Open Graph or Twitter card image with your text on a clean template and returns the PNG, JPEG or WebP bytes. Cards are cached, so repeated requests for the same parameters cost nothing and answer with an ETag.

Because the image URL usually goes in a <meta property="og:image"> tag where no header can be sent, the endpoint also accepts a signed URL: add k=<key id> and sig=<signature> instead of the Authorization header. The signature is the first 40 hex characters of HMAC-SHA256(secret, canonical query), where the canonical query is every parameter except sig, sorted by name and RFC 3986 encoded, and the secret is the signing secret shown for the key in the console.

GET https://api.zactonz.com/og/

Parameters

Name	Type	Description
`title`required	string	Main text, up to 120 characters.
`subtitle`	string	Secondary line, up to 200 characters.
`site`	string	Short label shown at the bottom, for example your domain, up to 60 characters.
`logo`	string	Public URL of a PNG, JPEG, WebP, GIF or SVG logo, up to 512 KB.
`template`	enum	`card` (accent bar and logo), `minimal` (centred) or `split` (text beside an accent panel). `cardminimalsplit`
`theme`	enum	`light` or `dark`. `lightdark`
`accent`	string	Accent colour as six hex digits. Default `ff6700`
`bg`	string	Background colour as six hex digits, overriding the theme.
`size`	enum	Pixel size. `1200x6301200x6001080x10801600x900`
`font`	enum	`titillium`, `system` or `serif`. `titilliumsystemserif`
`format`	enum	`png` (default), `jpeg` or `webp`. `pngjpegwebp`
`resp`	enum	`image` streams the bytes. `json` returns a hosted link valid for seven days. `imagejson`
`k`	integer	Key id, only for signed URLs.
`sig`	string	Signature, only for signed URLs.

Send parameters in the query string.

Response

Field	Type	Description
`status`	integer	`200` on success.
`data`	object	The result.
`data.image`	string	Hosted link to the card.
`data.format`	string	Image format.
`data.size`	string	Pixel size.
`data.cached`	boolean	Whether the card came from the cache.

Status codes

The outcome is reported in the JSON status field. See Errors & status codes for the general rules.

`400`	Bad request	`title` is missing or a parameter is out of range.
`422`	Logo unavailable	The logo URL did not return an image.
`503`	Renderer busy	All render slots are in use. Retry after a few seconds.
`504`	Timeout	Rendering did not finish within the time limit.
`401`	Unauthorized	The Authorization header is missing or the key is not recognised.
`403`	Forbidden	The key is not licensed for this product.
`429`	Too many requests	The per-minute rate or the plan quota is exhausted. Retry after the seconds given in `Retry-After`.

Notes

Titles wrap to three lines and are scaled to fit. Text is always escaped; HTML is not interpreted. A logo is fetched once, embedded in the render and never hot-linked.