JSON Schema & AI Workflow
Any quickthumb canvas can be written as JSON. A JSON spec can be generated by an LLM or a template, stored in a database, sent through an API, or kept in version control next to your content.
To generate, validate, and render a first spec, follow the AI workflow.
Use this page to look up layer fields, effects,
or the published schema. The quickthumb command requires
pip install "quickthumb[cli]"; Python schema helpers work without the CLI extra.
Round-trip serialization
Canonical JSON stores the authored document, separately from an export receipt:
from pathlib import Path
from quickthumb import Canvas
# Python → JSON
canvas = Canvas(320, 180).background(color="#102030")
json_str = canvas.to_json()
Path("scene.json").write_text(json_str, encoding="utf-8")
# JSON → Python
restored = Canvas.from_json(Path("scene.json").read_text(encoding="utf-8"))
assert restored.to_json() == json_str
restored.export("from-json.png")
Note
Canvas.from_json() expects a JSON string. If you have a Python dict, call json.dumps(data) first.
Canvases with .custom(fn) layers can't be serialized, because a Python function can't be stored as JSON.
Canonical serialization is deterministic for the same resolved document. It does not package fonts, images, media or cached downloads: retain referenced files and make their paths available when rendering elsewhere. Plugin JSON retains declared parameters and asset references, not Python callbacks; supply the matching explicit registry when loading it. Identical scene JSON does not guarantee identical pixels across fonts, renderer versions or platforms.
JSON structure
A Canvas JSON document has four required top-level fields, plus an optional theme block:
The top-level "kind" discriminator is required (by Canvas.from_json(), Deck.from_json(), and the CLI) and must be "canvas" or "deck".
Canvas documents carry layers; Deck documents carry slides and may also define a shared
default size, theme, and transitions. Every layer object requires its own "type"
discriminator field. Layers render in array order: the first item is at the back.
Layer identity, placement, alignment and motion use the same
shared vocabulary in Python, a Canvas JSON
root and every Deck slide. A Deck does not introduce a different layer schema.
Published schema
Emit the current JSON Schema from the same Pydantic models used by Canvas.from_json():
quickthumb schema > quickthumb.schema.json
quickthumb schema --output quickthumb.schema.json
quickthumb schema --document --output quickthumb.document-schema.json
The same schemas are available from Python as canvas_json_schema() and
document_json_schema(), and hosted with these docs:
- https://quickthumb.solaqua.dev/schema.json (Canvas)
- https://quickthumb.solaqua.dev/document-schema.json (Canvas or Deck)
To get completion and validation while editing specs in VS Code, map your
spec files to the hosted schema in .vscode/settings.json:
{
"json.schemas": [
{
"fileMatch": ["*.thumb.json"],
"url": "https://quickthumb.solaqua.dev/schema.json"
}
]
}
Use a file mapping like this rather than a "$schema" key inside the spec:
Canvas.from_json() rejects unknown top-level fields, including $schema.
The hosted files are regenerated on every docs deploy, which follows the main
branch. Run quickthumb schema to get the schema for the version you have
installed.
Schema scope
quickthumb schema describes concrete Canvas specs for external tooling and
constrained generation. Use quickthumb schema --document for the combined
Canvas/Deck discriminator schema. Canvas.from_json() remains the source of truth
for what quickthumb can load.
The CLI, serve, Canvas.from_json(), and Deck.from_json() all require
the matching top-level kind discriminator. Newly serialized documents
include the discriminator at every document boundary, including Deck slides.
Deck slides may omit width and height when the Deck supplies default
dimensions; the document schema accepts that form and canonical JSON emits
the inherited dimensions on each slide. Transition objects use the same
discriminated, strict contract as Deck.from_json().
Authoring conveniences such as $theme.* are resolved by quickthumb before
model validation, so generic JSON Schema validators may reject unresolved
authoring specs that quickthumb itself can load.
The command writes deterministic JSON only, so it can be checked into a repo, piped into an editor, or passed directly to a constrained-generation API. The Canvas schema includes the current canvas fields, built-in layer discriminators, effects, animations, supported platform presets, and the optional top-level theme block. The --document schema adds the Deck root and maps both document kinds through kind.
Plugin layers
Plugin registrations are kept in one explicit PluginRegistry. A registration
describes a layer type and its parameters. A separate trusted synchronous
raster callback renders plugin layers as canonical RGBA pixels.
Callbacks are application code, never serialized or imported from JSON.
from quickthumb import Canvas, PluginRegistry, canvas_json_schema
registry = PluginRegistry()
registry.register(
"brand_badge",
"1.0",
params_schema={
"type": "object",
"required": ["label"],
"properties": {"label": {"type": "string"}},
"additionalProperties": False,
},
)
canvas = Canvas.from_json(text, registry=registry)
schema = canvas_json_schema(registry=registry)
A plugin layer requires type: "plugin", renderer, version, object-valued
params, and positive integer width/height. position accepts the normal
pixel/percentage coordinates; align and opacity affect its local box. Standard
clip and mask boundaries apply after rendering. A Group controls child
placement and can animate the whole group, including static plugin pixels. The same
explicit registry must be supplied to document parsers and Schema helpers.
from PIL import Image
def badge(params, context):
with Image.new("RGBA", context.size, params["color"]) as image:
return image.tobytes()
registry.register("badge", "1", raster=badge)
canvas = Canvas(320, 180, registry=registry).plugin(
"badge", version="1", params={"color": "#42CEB7"},
position=(20, 30), width=120, height=40,
)
canvas.export("badge.png")
The raster callback receives a params dict and context.size, returning raw RGBA8 bytes (width * height * 4). Declare external assets via assets={"texture": "assets/texture.png"} on the layer and access them with context.read_asset("texture").
Optional native SVG
For vector outputs, register an optional svg= callback returning an SVG string:
def badge_svg(params, context):
width, height = context.size
return (
f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}">'
f'<rect width="{width}" height="{height}" fill="{params["color"]}"/></svg>'
)
registry.register("badge", "1", raster=badge, svg=badge_svg)
In formats that don't support native SVG plugins, the layer automatically falls back to rendering via its raster callback.
Plugin params Schema v1
params_schema accepts the documented quickthumb plugin-params v1 subset. It
supports the JSON types object, array, string, number, integer,
boolean, and null; required, properties, additionalProperties,
items; const, enum, oneOf, anyOf; string patterns and size limits; and
numeric minimum/maximum limits. Unsupported keywords such as $ref, allOf,
and not are rejected during registration so the published Schema and runtime
validation stay in agreement.
The process-global plugin_registry remains available for applications that
want a shared default. For tests, services, and libraries, prefer an explicit
PluginRegistry so registrations stay isolated and reproducible.
For constrained generation, prefer concrete resolved values in typed fields:
Use quickthumb.schema.json as the JSON response schema.
Generate one valid quickthumb canvas spec for a 1280x720 YouTube thumbnail.
Return only the JSON object.
Use concrete hex colors and numeric sizes in layer fields.
Use only these layer type discriminators: background, text, image, shape, svg, group, outline.
Theme tokens
Define brand tokens once in a top-level theme block and reference them anywhere in the spec with $theme.path:
{
"kind": "canvas",
"width": 1280,
"height": 720,
"theme": {
"colors": { "primary": "#B8FF00", "ink": "#111111" },
"sizes": { "title": 96 }
},
"layers": [
{ "type": "background", "color": "$theme.colors.ink" },
{ "type": "text", "content": "Hello", "size": "$theme.sizes.title", "color": "$theme.colors.primary" }
]
}
Rules:
- The
themeblock can nest groups arbitrarily; reference paths with dots:$theme.colors.primary. - A whole-string reference keeps its native JSON type:
"size": "$theme.sizes.title"resolves to the number96, and tokens can hold lists too. - Scalar tokens (strings, numbers) can also be embedded inside longer strings.
- Theme values may reference other theme tokens (aliases). Circular references raise
ValidationError. - Referencing an undefined token raises
ValidationError. - Tokens are resolved at parse time:
to_json()emits resolved values without thethemeblock. - Theme tokens work alongside
$vartemplate substitution (quickthumb render --var KEY=VALUE);$theme.*references are never treated as variables.
Layer schemas
The most common layers are shown below. Video, chart, QR code, counter, and plugin layers follow the same pattern; their fields are in the published schema and on their API reference pages.
Background layer
{
"type": "background",
"color": "#0F172A",
"gradient": null,
"image": null,
"opacity": 1.0,
"blend_mode": null,
"fit": null,
"effects": []
}
Only include the fields you need; the rest use their defaults.
Gradient variants:
{
"type": "background",
"gradient": {
"type": "linear",
"angle": 120,
"stops": [["#111827", 0.0], ["#11182700", 1.0]]
}
}
{
"type": "background",
"gradient": {
"type": "radial",
"stops": [["#00000000", 0.0], ["#000000CC", 1.0]],
"center": [0.5, 0.5]
}
}
Image background:
{
"type": "background",
"image": "https://example.com/photo.jpg",
"fit": "cover",
"blend_mode": "multiply",
"effects": [
{ "type": "filter", "blur": 4, "brightness": 0.75, "contrast": 1.1, "saturation": 0.9 }
]
}
Text layer
{
"type": "text",
"content": "Hello World",
"font_source": "auto",
"font_variations": {},
"emoji_style": "monochrome",
"size": 72,
"color": "#FFFFFF",
"position": ["50%", "50%"],
"align": "center",
"max_height": null,
"min_size": 1,
"balance_lines": false,
"opacity": 1.0,
"rotation": 0.0,
"effects": []
}
Rich text with TextPart list:
{
"type": "text",
"content": [
{
"text": "5 ",
"color": "#FBBF24",
"font_source": null,
"font_variations": null,
"emoji_style": null,
"weight": 900,
"effects": []
},
{
"text": "WARNING SIGNS",
"color": "#FFFFFF",
"font_source": "auto",
"font_variations": {},
"emoji_style": "monochrome",
"weight": 900,
"effects": []
}
],
"size": 80,
"position": ["8%", "55%"],
"align": "left",
"max_width": "65%",
"auto_scale": false,
"rotation": 0.0,
"opacity": 1.0,
"effects": [
{ "type": "stroke", "width": 3, "color": "#000000" },
{ "type": "shadow", "offset_x": 4, "offset_y": 4, "color": "#000000", "blur_radius": 8 }
]
}
Gradient-filled text:
{
"type": "text",
"content": "GRADIENT",
"size": 120,
"fill": {
"type": "linear",
"angle": 90,
"stops": [["#FF6B6B", 0.0], ["#4ECDC4", 1.0]]
},
"position": ["50%", "50%"],
"align": "center",
"effects": []
}
Image-filled text:
{
"type": "text",
"content": "TEXTURE",
"size": 140,
"fill": {
"type": "image",
"path": "fire_texture.jpg",
"fit": "cover"
},
"position": ["50%", "50%"],
"align": "center",
"effects": []
}
fill discriminator values: "linear", "radial", "image", the same tags as background gradients. fill can also be set per TextPart entry using the same discriminated object.
Align values: "center", "left", "right", "top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"
Image layer
{
"type": "image",
"path": "portrait.png",
"position": ["74%", "54%"],
"width": 420,
"height": 520,
"fit": "cover",
"align": "center",
"opacity": 1.0,
"rotation": 0.0,
"remove_background": false,
"border_radius": 24,
"blend_mode": "normal",
"effects": [
{ "type": "filter", "contrast": 1.1, "saturation": 1.05 },
{ "type": "shadow", "offset_x": 0, "offset_y": 12, "color": "#000000", "blur_radius": 24 }
]
}
Shape layer
{
"type": "shape",
"shape": "rectangle",
"position": [48, 48],
"width": 320,
"height": 96,
"color": "#CC0000",
"border_radius": 14,
"opacity": 1.0,
"rotation": 0.0,
"align": "top-left",
"effects": [
{ "type": "stroke", "width": 2, "color": "#FFFFFF" }
]
}
"shape" values: "rectangle", "ellipse", "pill", "triangle", "star", "polygon"
Star and polygon variants:
{
"type": "shape",
"shape": "star",
"position": ["80%", "50%"],
"width": 280,
"height": 280,
"color": "#7C5CFF",
"align": "center",
"rotation": 12,
"star_points": 5,
"inner_radius": 0.45
}
{
"type": "shape",
"shape": "polygon",
"position": [600, 60],
"width": 160,
"height": 100,
"color": "#53BF9D",
"points": [[0.0, 0.25], [0.6, 0.25], [0.6, 0.0], [1.0, 0.5], [0.6, 1.0], [0.6, 0.75], [0.0, 0.75]]
}
points is required for "polygon" (and only valid there): at least 3 vertices, normalized 0.0–1.0 inside the shape box. star_points (≥ 3) and inner_radius (between 0 and 1, exclusive) only apply to "star".
SVG layer
Rasterized at render time. Requires the quickthumb[svg] extra. See the SVG reference.
{
"type": "svg",
"path": "logo.svg",
"position": ["92%", "10%"],
"width": 120,
"align": "center",
"opacity": 1.0,
"rotation": 0.0,
"blend_mode": null,
"effects": []
}
width/height set the raster size; aspect ratio is preserved when only one is given. SVG layers accept the same effects as image layers.
Group layer
Auto-layout container: children are measured and stacked along a row or column, so they must not set position. See the Group reference.
{
"type": "group",
"direction": "column",
"gap": 24,
"padding": 0,
"position": ["8%", "50%"],
"align": ["left", "middle"],
"item_align": "start",
"children": [
{ "type": "shape", "shape": "pill", "width": 120, "height": 36, "color": "#E94560" },
{ "type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900 },
{ "type": "text", "content": "No coordinates were harmed", "size": 40, "color": "#A2A8D3" }
]
}
direction:"column"(default) or"row"gap: pixels between children;padding: int,[vertical, horizontal], or[top, right, bottom, left]item_align: cross-axis placement, one of"start","center", or"end"childrentypes:"text","image","shape","svg", or nested"group"
Outline layer
Effect schemas
Effects are embedded in each layer's "effects" array and use a "type" discriminator:
blend_mode values: "overlay", "screen", "multiply", "normal". Optional "seed" integer for deterministic output.
Which effects each layer accepts is listed in the Effects reference.
Complete example
A full YouTube-style thumbnail spec:
{
"kind": "canvas",
"width": 1280,
"height": 720,
"layers": [
{
"type": "background",
"image": "https://images.unsplash.com/photo-1516321318423-f06f85e504b3",
"fit": "cover",
"effects": [{ "type": "filter", "brightness": 0.6 }]
},
{
"type": "background",
"color": "#000000",
"opacity": 0.35
},
{
"type": "shape",
"shape": "rectangle",
"position": [52, 52],
"width": 360,
"height": 96,
"color": "#CC0000",
"border_radius": 14,
"effects": []
},
{
"type": "text",
"content": [
{ "text": "AI ", "color": "#B8FF00", "weight": 900, "effects": [] },
{ "text": "THUMBNAILS", "color": "#FFFFFF", "weight": 900, "effects": [] }
],
"size": 108,
"position": ["8%", "52%"],
"align": "left",
"max_width": "58%",
"rotation": 0.0,
"opacity": 1.0,
"effects": [
{ "type": "stroke", "width": 6, "color": "#000000" },
{ "type": "shadow", "offset_x": 4, "offset_y": 4, "color": "#000000", "blur_radius": 8 }
]
},
{
"type": "image",
"path": "portrait.png",
"position": ["75%", "55%"],
"width": 430,
"height": 540,
"fit": "cover",
"align": "center",
"border_radius": 24,
"effects": [
{ "type": "shadow", "offset_x": 0, "offset_y": 14, "color": "#000000", "blur_radius": 24 }
]
},
{
"type": "outline",
"width": 12,
"color": "#B8FF00",
"offset": 0,
"opacity": 1.0
}
]
}
Generating specs with an LLM
The AI Workflow recipe covers this end to end:
giving the model the published schema, sending validation errors and
diagnose() findings back to it, and asking for edits instead of new
designs.
Serialization notes
| Field | Serialized form |
|---|---|
align |
String: "center", "top-left", etc. |
blend_mode |
String: "multiply", "normal", etc. |
fit |
String: "cover", "contain", "fill" |
position |
JSON array: [640, 360] or ["50%", "50%"] |
| Gradient stops | JSON array of ["#color", 0.0] pairs |
null fields |
Omitted fields default to null / their default value |
theme block |
Resolved at parse time; to_json() emits resolved values without the theme block |