Shorts / 竖版封面

一款整套设计均使用 JSON 文件声明的 1080×1920 封面。Python 端仅负责加载并执行渲染,这正是通过大语言模型(LLM)或模板系统生成排版时的典型使用方式。
安装 uv 并克隆代码仓库即可运行此示例:
git clone https://github.com/sjquant/quickthumb
cd quickthumb
uv run python examples/shorts_cover_agent.py
该脚本将写入 examples/shorts_cover_agent.png,并覆盖同名旧文件。
构成方式
- 同一张照片,复用两次。 同一张图片分别以 16:9 横向裁切显示,并置于手机屏幕内部。
"fit": "cover"会将其自动裁切以适应各个画框的形状。 - 手机模型由两个图层构成。 深色的圆角矩形作为机身外壳,上层的照片作为屏幕内容。两者以及屏幕上的三个标签均设置了
"rotation": 3,从而保持一致的倾斜角度。 - 素材路径相对于代码仓库根目录。 例如
assets/images/denise-jans-WIRvXd1PYlg-unsplash.jpg。脚本在渲染前会自动切换至仓库根目录,因此支持在任意工作目录下运行。 - 背景添加了轻微胶片颗粒。 使用带有固定
seed的grain效果,确保每次渲染都能得到完全确定的颗粒质感。
规范定义
{
"kind": "canvas",
"width": 1080,
"height": 1920,
"layers": [
{
"type": "background",
"color": "#F5F5F7",
"effects": [
{ "type": "grain", "intensity": 0.006, "monochrome": true, "seed": 9 }
]
},
{
"type": "text",
"content": "JSON WORKFLOW / 01",
"font": "Roboto",
"size": 24,
"color": "#6E6E73",
"position": ["8%", "7%"],
"weight": 700,
"letter_spacing": 3
},
{
"type": "shape",
"shape": "rectangle",
"position": ["8%", "10%"],
"width": 908,
"height": 1,
"color": "#1D1D1F26"
},
{
"type": "text",
"content": [
{ "text": "TURN LONG VIDEOS\nINTO ", "color": "#1D1D1F", "weight": 700 },
{ "text": "SHORTS.", "color": "#0066CC", "weight": 700 }
],
"font": "Roboto",
"size": 102,
"position": ["8%", "16%"],
"max_width": "84%",
"line_height": 1.0,
"letter_spacing": -2
},
{
"type": "text",
"content": "JSON in.\nCover out.",
"font": "Roboto",
"size": 42,
"color": "#6E6E73",
"position": ["8%", "43%"],
"line_height": 1.18
},
{
"type": "shape",
"shape": "rectangle",
"position": ["0%", "50%"],
"width": 1080,
"height": 720,
"color": "#0066CC"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["77%", "56%"],
"width": 430,
"height": 850,
"color": "#0A0A0A",
"border_radius": 50,
"rotation": 3,
"align": "center",
"effects": [
{ "type": "stroke", "width": 1, "color": "#D2D2D7" },
{ "type": "shadow", "offset_x": 0, "offset_y": 22, "color": "#00000038", "blur_radius": 32 }
]
},
{
"type": "image",
"path": "assets/images/denise-jans-WIRvXd1PYlg-unsplash.jpg",
"position": ["77%", "56%"],
"width": 376,
"height": 728,
"fit": "cover",
"rotation": 3,
"align": "center",
"border_radius": 34,
"effects": [
{ "type": "filter", "brightness": 0.9, "contrast": 1.04, "saturation": 0.72, "blur": 0 }
]
},
{
"type": "shape",
"shape": "rectangle",
"position": ["8%", "64%"],
"width": 430,
"height": 242,
"color": "#FFFFFF14",
"border_radius": 18,
"effects": [{ "type": "stroke", "width": 2, "color": "#FFFFFF" }]
},
{
"type": "text",
"content": "16:9 SOURCE",
"font": "Roboto",
"size": 24,
"color": "#FFFFFF",
"position": ["8%", "60%"],
"weight": 700,
"letter_spacing": 2
},
{
"type": "image",
"path": "assets/images/denise-jans-WIRvXd1PYlg-unsplash.jpg",
"position": ["8%", "64%"],
"width": 430,
"height": 242,
"fit": "cover",
"border_radius": 18,
"effects": [
{ "type": "filter", "brightness": 0.76, "contrast": 1.08, "saturation": 0.58, "blur": 0 }
]
},
{
"type": "text",
"content": "TO / 9:16 × 3",
"font": "Roboto",
"size": 40,
"color": "#FFFFFF",
"position": ["8%", "80%"],
"weight": 700,
"letter_spacing": 2
},
{
"type": "shape",
"shape": "rectangle",
"position": ["77%", "47%"],
"width": 330,
"height": 2,
"color": "#FFFFFFCC",
"rotation": 3,
"align": "center"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["77%", "58%"],
"width": 330,
"height": 2,
"color": "#FFFFFFCC",
"rotation": 3,
"align": "center"
},
{
"type": "text",
"content": "01 HOOK",
"font": "Roboto",
"size": 18,
"color": "#FFFFFF",
"position": ["65%", "41%"],
"weight": 700,
"letter_spacing": 2,
"rotation": 3,
"effects": [{ "type": "shadow", "offset_x": 0, "offset_y": 2, "color": "#000000CC", "blur_radius": 5 }]
},
{
"type": "text",
"content": "02 CUT",
"font": "Roboto",
"size": 18,
"color": "#FFFFFF",
"position": ["65%", "52%"],
"weight": 700,
"letter_spacing": 2,
"rotation": 3,
"effects": [{ "type": "shadow", "offset_x": 0, "offset_y": 2, "color": "#000000CC", "blur_radius": 5 }]
},
{
"type": "text",
"content": "03 CAPTION",
"font": "Roboto",
"size": 18,
"color": "#FFFFFF",
"position": ["65%", "63%"],
"weight": 700,
"letter_spacing": 2,
"rotation": 3,
"effects": [{ "type": "shadow", "offset_x": 0, "offset_y": 2, "color": "#000000CC", "blur_radius": 5 }]
},
{
"type": "shape",
"shape": "rectangle",
"position": ["8%", "88%"],
"width": 908,
"height": 1,
"color": "#1D1D1F26"
},
{
"type": "text",
"content": [
{ "text": "AGENT EMITS JSON", "color": "#1D1D1F", "weight": 700 },
{ "text": " / QUICKTHUMB RENDERS", "color": "#6E6E73", "weight": 500 }
],
"font": "Roboto",
"size": 28,
"position": ["8%", "91%"],
"max_width": "84%"
}
]
}
脚本代码
"""
JSON-first vertical cover example.
This script simulates the workflow where an AI agent emits a quickthumb JSON spec
and the application renders it with `Canvas.from_json(...)`.
"""
import os
from quickthumb import Canvas
FILE_DIR = os.path.dirname(__file__)
REPO_DIR = os.path.abspath(os.path.join(FILE_DIR, ".."))
SPEC_PATH = os.path.join(FILE_DIR, "shorts_cover_agent.json")
OUTPUT_PATH = os.path.join(FILE_DIR, "shorts_cover_agent.png")
os.environ["QUICKTHUMB_FONT_DIR"] = os.path.join(REPO_DIR, "assets", "fonts")
os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
with open(SPEC_PATH, encoding="utf-8") as f:
json_spec = f.read()
previous_cwd = os.getcwd()
try:
# The checked-in JSON spec uses repo-relative asset paths to stay easy to read.
os.chdir(REPO_DIR)
Canvas.from_json(json_spec).render(OUTPUT_PATH)
finally:
os.chdir(previous_cwd)
print(f"✓ JSON-first Shorts cover created: {OUTPUT_PATH}")
print(f" Spec source: {SPEC_PATH}")
Canvas.from_json() 会在绘制任何像素前严格校验规范,因此格式错误的规范会抛出指出具体错误字段的 ValidationError。规范支持的完整字段列表请参阅 JSON Schema 与 AI 工作流。