Skip to content
quickthumb
All documentation

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:

{
  "kind": "canvas",
  "width": 1280,
  "height": 720,
  "theme": { ... },
  "layers": [ ... ]
}

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:

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 theme block 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 number 96, 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 the theme block.
  • Theme tokens work alongside $var template 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"
  • children types: "text", "image", "shape", "svg", or nested "group"

Outline layer

{
  "type": "outline",
  "width": 12,
  "color": "#B8FF00",
  "offset": 0,
  "opacity": 1.0
}

Effect schemas

Effects are embedded in each layer's "effects" array and use a "type" discriminator:

{ "type": "stroke", "width": 4, "color": "#000000" }
{ "type": "shadow", "offset_x": 4, "offset_y": 8, "color": "#000000", "blur_radius": 12 }
{ "type": "glow", "color": "#B8FF00", "radius": 16, "opacity": 0.35 }
{ "type": "filter", "blur": 4, "brightness": 0.75, "contrast": 1.1, "saturation": 0.9 }
{ "type": "background", "color": "#111827CC", "padding": [16, 24], "border_radius": 14, "opacity": 1.0 }
{ "type": "grain", "intensity": 0.12, "monochrome": true, "blend_mode": "overlay", "opacity": 1.0 }

blend_mode values: "overlay", "screen", "multiply", "normal". Optional "seed" integer for deterministic output.

{ "type": "duotone", "shadows": "#0A1730", "highlights": "#7FADFF", "opacity": 1.0 }
{ "type": "inner_shadow", "offset_x": 0, "offset_y": 6, "color": "#00000080", "blur_radius": 12, "opacity": 1.0 }
{ "type": "backdrop_blur", "radius": 24, "opacity": 1.0 }

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