Image Template Library¶
Two public catalogue endpoints describe the pre-built Liquid image templates:
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/v1/image/templates |
List every template, optionally filtered by category |
GET |
/v1/image/templates/{template_id} |
Full metadata (incl. SEO fields) for one template |
Base URL: https://image.toolkitapi.io
The point of these endpoints is the template_url field: pass it straight into POST /v1/image/from-template together with a variables object, and you get a rendered PNG/JPEG/WebP back. Use the catalogue to discover template IDs and discover which Liquid variables each template accepts.
Both endpoints are intended for agents and no-code tools — they return template_url values you can use directly, plus the recommended canvas size and a typed list of variables with defaults.
List templates¶
GET /v1/image/templates
| Query param | Type | Required | Description |
|---|---|---|---|
category |
string | ❌ | Filter to one category (see below). Matching is case-insensitive; unknown values return count: 0 |
Categories¶
| Category | What it's for | Canvas sizes |
|---|---|---|
open-graph |
og:image meta tags, blog/product/quote cards |
1200×630 |
youtube-thumbnail |
Video thumbnails | 1280×720 |
social-post |
Square social posts and announcements | 1080×1080 |
banner |
Wide promotional banners | 1200×400, 1584×396 |
professional-card |
Team member / profile cards | 1024×576 |
certificate |
Achievement certificates | 1200×840 |
?category= on an unrecognised value (e.g. ?category=poster) is not an error — you get an empty templates array with count: 0.
# Everything
curl "https://image.toolkitapi.io/v1/image/templates" -H "X-API-Key: YOUR_KEY"
# One category
curl "https://image.toolkitapi.io/v1/image/templates?category=open-graph" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/templates",
headers={"X-API-Key": "YOUR_KEY"},
params={"category": "youtube-thumbnail"},
)
resp.raise_for_status()
data = resp.json()
for t in data["templates"]:
print(f"{t['id']:20} {t['width']}x{t['height']} {t['name']}")
const url = new URL("https://image.toolkitapi.io/v1/image/templates");
url.searchParams.set("category", "youtube-thumbnail");
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
const { count, templates } = await resp.json();
console.log(`${count} templates`);
for (const t of templates) console.log(t.id, `${t.width}x${t.height}`);
Response
{
"count": 3,
"templates": [
{
"id": "yt-title-card",
"name": "YouTube Bold Title Card",
"output_type": "image",
"category": "youtube-thumbnail",
"description": "High-contrast thumbnail with a large headline and optional kicker line.",
"template_url": "https://toolkitapi.io/static/templates/image/yt-title-card.html",
"preview_url": "https://toolkitapi.io/static/templates/image/previews/yt-title-card.png",
"width": 1280,
"height": 720,
"tags": ["youtube", "thumbnail", "title", "bold"],
"use_cases": ["Video thumbnails", "Podcast episode covers"],
"seo_title": "YouTube Bold Title Card Template — 1280×720",
"seo_description": "Bold, high-contrast YouTube thumbnail with a single dominant headline.",
"variables": [
{
"name": "title",
"type": "string",
"default": "How We Shipped It",
"description": "Main headline text"
},
{
"name": "bg_color",
"type": "color",
"default": "#111827",
"description": "Background colour"
}
]
}
]
}
Template fields¶
| Field | Type | Description |
|---|---|---|
id |
string | Stable template identifier — use this with /from-template via template_url |
name |
string | Human-readable name |
output_type |
string | Always image on this toolkit |
category |
string | One of the categories above |
description |
string | Short summary of the design |
template_url |
string | HTML template to pass as template_url in render requests |
preview_url |
string | null | Example render, useful for pickers and docs |
width / height |
integer | Recommended canvas size in pixels |
tags |
string[] | Keywords for search/UI filtering |
use_cases |
string[] | Suggested applications |
seo_title |
string | null | Pre-written page title for template drilldown pages |
seo_description |
string | null | Pre-written meta description |
variables |
array | Liquid variables the template understands (see below) |
Each entry in variables:
| Field | Type | Description |
|---|---|---|
name |
string | Liquid variable name — this is the key you set in variables |
type |
string | string, color, url, number, or array |
default |
string | null | Value used when you omit the variable |
description |
string | null | What the variable controls |
Get one template¶
GET /v1/image/templates/{template_id}
Returns a single object (not wrapped in count/templates) with the same fields, including the SEO metadata — ideal for building a drilldown page.
curl "https://image.toolkitapi.io/v1/image/templates/og-article" \
-H "X-API-Key: YOUR_KEY"
tpl = requests.get(
"https://image.toolkitapi.io/v1/image/templates/og-article",
headers={"X-API-Key": "YOUR_KEY"},
).json()
print(tpl["name"], tpl["width"], "x", tpl["height"])
print("vars:", ", ".join(v["name"] for v in tpl["variables"]))
const resp = await fetch(
"https://image.toolkitapi.io/v1/image/templates/og-article",
{ headers: { "X-API-Key": "YOUR_KEY" } }
);
if (resp.status === 404) throw new Error("No such template");
const tpl = await resp.json();
console.log(tpl.name, tpl.variables.map((v) => v.name).join(", "));
Available templates¶
id |
Name | Category | Size |
|---|---|---|---|
og-article |
Article Card | open-graph | 1200×630 |
og-product |
Product Card | open-graph | 1200×630 |
og-minimal |
Minimal Brand Card | open-graph | 1200×630 |
og-github |
Project / GitHub Card | open-graph | 1200×630 |
og-quote |
Pull Quote Card | open-graph | 1200×630 |
yt-title-card |
YouTube Bold Title Card | youtube-thumbnail | 1280×720 |
yt-versus |
YouTube A vs B Comparison | youtube-thumbnail | 1280×720 |
yt-listicle |
YouTube Top N List | youtube-thumbnail | 1280×720 |
sm-announcement |
Launch / Announcement Post | social-post | 1080×1080 |
sm-quote |
Quote Card | social-post | 1080×1080 |
sm-testimonial |
Customer Testimonial / Review | social-post | 1080×1080 |
sm-stat |
Stat / Metric Card | social-post | 1080×1080 |
banner-sale |
Sale / Promotion Banner | banner | 1200×400 |
banner-event |
Event Banner | banner | 1200×400 |
banner-linkedin |
LinkedIn Cover Banner | banner | 1584×396 |
card-profile |
Team Member Profile Card | professional-card | 1024×576 |
img-certificate |
Achievement Certificate Card | certificate | 1200×840 |
The catalogue is versioned with the API — always call /v1/image/templates rather than hard-coding this list, since new templates are added over time.
Rendering a catalogue template¶
The full round trip: discover → render.
import requests
HEADERS = {"X-API-Key": "YOUR_KEY"}
BASE = "https://image.toolkitapi.io"
# 1. Find an open-graph template
tpl = requests.get(
f"{BASE}/v1/image/templates",
headers=HEADERS,
params={"category": "open-graph"},
).json()["templates"][0]
# 2. Build variables from the declared spec
variables = {v["name"]: v["default"] for v in tpl["variables"] if v["default"]}
variables.update({
"title": "Shipping Toolkit v2",
"author": "Chris Morgan",
"site_name": "Toolkit API",
})
# 3. Render
img = requests.post(
f"{BASE}/v1/image/from-template",
headers=HEADERS,
json={
"template_url": tpl["template_url"],
"variables": variables,
"width": tpl["width"],
"height": tpl["height"],
"format": "png",
},
).json()
print(img["image_url"] or "base64 returned")
const HEADERS = { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" };
const BASE = "https://image.toolkitapi.io";
const list = await (await fetch(`${BASE}/v1/image/templates?category=open-graph`, { headers: HEADERS })).json();
const tpl = list.templates[0];
const variables = Object.fromEntries(
tpl.variables.filter((v) => v.default).map((v) => [v.name, v.default])
);
Object.assign(variables, { title: "Shipping Toolkit v2", site_name: "Toolkit API" });
const render = await fetch(`${BASE}/v1/image/from-template`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
template_url: tpl.template_url,
variables,
width: tpl.width,
height: tpl.height,
format: "png",
}),
});
const img = await render.json();
console.log(img.image_url ?? "base64 returned");
Error cases¶
| Status | When | Body |
|---|---|---|
401 |
Missing or invalid API key | {"detail": "Invalid or missing API key"} |
404 |
template_id not in the catalogue |
{"detail": "Template 'og-nope' not found."} |
The list endpoint never returns 404 — an unknown category produces an empty result with count: 0.
Tips¶
template_urlis the contract, notid./from-templateaccepts a URL, so store thetemplate_urlvalue rather than reconstructing it from the id.- Seed variables from defaults. Starting from
variables[].defaultand overriding the fields you care about produces a sensible image even if you miss a required-looking field — every catalogue template ships with defaults for all variables. - Respect the recommended size. Rendering a 1200×630 layout at 1080×1080 stretches text. Use
width/heightfrom the catalogue, or pick a template whose canvas matches your target. typeis advisory. Thecolorandurltypes tell you the expected format (#rrggbb, absolute URL) — the renderer does not validate them, so bad input silently renders badly.- Cache the catalogue. It changes rarely; one fetch per process start is plenty. Cache the responses in your UI to power template pickers without paging.
preview_urlfor empty states. Show it before a user customises anything so the picker isn't a wall of blank placeholders.- SEO fields are for your page, not the image.
seo_title/seo_descriptionare pre-written copy for template drilldown pages — useful if you're building a gallery.
Related¶
- Template Rendering — render with
POST /v1/image/from-template - Extraction — pull dominant colours and metadata from an image
- Generation & Watermarking — free-form HTML → image rendering