URL Parameters Reference

Every image generated by /v1/images/{layout}.png is customized via URL query parameters.

The API uses strict parameter validation: unknown parameters, invalid characters, or values outside permitted ranges result in an immediate HTTP 400 (invalid_parameter or unknown_parameter) error response.

---

Global Query Parameters

Parameter	Type	Required	Default	Validation & Constraints
title	string	Yes	—	Length: 1 to 120 characters. Trimmed. Required across all layouts.
subtitle	string	No	—	Length: 0 to 80 characters. Secondary heading text.
description	string	No	—	Length: 0 to 240 characters. Explanatory paragraph or summary body.
size	string	No	og	Enum: og (1200×630), twitter (1200×600), square (1200×1200).
theme	string	No	dark	Enum: dark, light. Controls default contrast palettes.
bg	string	No	Layout default	Hex color code (3 or 6 characters, e.g. 0a0a0a or fff). Do not include #.
bg2	string	No	—	Hex color code for secondary gradient stop. When omitted, background is solid or image-backed.
angle	number	No	135	Integer: 0 to 360. Gradient rotation angle in degrees (requires bg2).
bg_image	string	No	—	Publicly routable HTTPS URL for canvas backdrop (max 2 MB).
bg_overlay	number	No	75	Integer: 0 to 100. Contrast tint opacity percentage over bg_image (requires bg_image).
color	string	No	Layout default	Primary foreground text color (3 or 6 hex characters without #).
accent	string	No	Layout default	Accent color for highlight rules, tags, and borders (hex without #).
font	string	No	inter	Enum: inter (sans), source-serif-4 (serif), jetbrains-mono (mono).
align	string	No	Layout default	Enum: left, center. Text alignment for headings and descriptions.
image	string	No	—	Publicly routable HTTPS URL for featured content mockup or screenshot (max 2 MB).
image_fit	string	No	cover	Enum: cover, contain. Scaling mode for content image.
image_radius	string	No	rounded	Enum: rounded (16px), circle (100%), square (0px).
image_border	string	No	subtle	Enum: subtle (1px translucent edge), none.
logo	string	No	—	Publicly routable HTTPS URL to brand logo (PNG, JPEG, or SVG, max 2 MB).
logo_fit	string	No	contain	Enum: contain, cover. Scaling mode for brand mark.
logo_radius	string	No	rounded	Enum: rounded, circle, square.
logo_border	string	No	none	Enum: none, subtle.
avatar	string	No	—	Publicly routable HTTPS URL to user avatar (PNG or JPEG, max 2 MB).
avatar_fit	string	No	cover	Enum: cover, contain. Scaling mode for avatar.
avatar_radius	string	No	circle	Enum: circle, rounded, square.
avatar_border	string	No	none	Enum: none, subtle.
author	string	No	—	Length: 0 to 40 characters. Author name or handle.
v	string	No	—	Cache buster string ([a-z0-9]{1,16}, e.g. v=2 or v=ab3f).

---

Layout Parameter Support Matrix

Not all layouts consume every query parameter. Supplying an unsupported parameter returns an invalid_parameter or unknown_parameter error.

The table below reflects the exact capabilities of each built-in layout:

Parameter	minimal	article	docs	product	profile	announcement
title	Yes	Yes	Yes	Yes	Yes	Yes
subtitle	—	Yes	Yes	Yes	Yes	Yes
description	—	Yes	Yes	—	Yes	Yes
size	Yes	Yes	Yes	Yes	Yes	Yes
theme	Yes	Yes	Yes	Yes	Yes	Yes
bg	Yes	Yes	Yes	Yes	Yes	Yes
bg2	Yes	Yes	Yes	Yes	Yes	Yes
angle	Yes	Yes	Yes	Yes	Yes	Yes
bg_image	Yes	Yes	Yes	Yes	Yes	Yes
bg_overlay	Yes	Yes	Yes	Yes	Yes	Yes
color	Yes	Yes	Yes	Yes	Yes	Yes
accent	Yes	Yes	Yes	Yes	Yes	Yes
font	Yes	Yes	Yes	Yes	Yes	Yes
align	Yes	Yes	Yes	Yes	Yes	Yes
image	Yes	Yes	Yes	Yes	Yes	Yes
image_fit	Yes	Yes	Yes	Yes	Yes	Yes
image_radius	Yes	Yes	Yes	Yes	Yes	Yes
image_border	Yes	Yes	Yes	Yes	Yes	Yes
logo	—	—	Yes	Yes	—	Yes
logo_fit	—	—	Yes	Yes	—	Yes
logo_radius	—	—	Yes	Yes	—	Yes
logo_border	—	—	Yes	Yes	—	Yes
avatar	—	Yes	—	—	Yes	—
avatar_fit	—	Yes	—	—	Yes	—
avatar_radius	—	Yes	—	—	Yes	—
avatar_border	—	Yes	—	—	Yes	—
author	—	Yes	—	—	—	—
v	Yes	Yes	Yes	Yes	Yes	Yes

---

Color Formatting & Syntax

Colors must be passed as raw 3-digit or 6-digit hex values without the leading hash (#) symbol:

• Correct: bg=0a0a0a&color=f4f4f5&accent=3b82f6
• Incorrect: bg=%230a0a0a (fails validation with invalid_parameter)

If bg2 is provided alongside bg, the renderer applies a linear gradient calculated from angle (default: 135 degrees).

---

Text Encoding & Length Limits

• Maximum URL Length: 2,048 characters total. If your request exceeds this, the edge returns HTTP 414 (uri_too_long).
• Encoding: Always URL-encode values containing spaces, ampersands, or Unicode characters:
  • Space: %20 or +
  • Ampersand: %26
  • Quotation marks: %22
  • Slash: %2F

For interactive experimentation with automatic parameter validation, visit the Playground.