跳转至
quickthumb
全部文档

Shorts / 竖版封面

竖版封面,带有倾斜的手机模型展示裁切照片,配有“Turn long videos into 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 工作流。