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_url is the contract, not id. /from-template accepts a URL, so store the template_url value rather than reconstructing it from the id.
  • Seed variables from defaults. Starting from variables[].default and 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/height from the catalogue, or pick a template whose canvas matches your target.
  • type is advisory. The color and url types 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_url for 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_description are pre-written copy for template drilldown pages — useful if you're building a gallery.