渲染接口 /og

生成一张 OG 图像。支持两种写法，路径形式优先于 query：

GET /og?template=<name>&<字段>...
GET /og/<name>?<字段>...

当 template 同时在路径和 ?template= 出现时，以路径段为准。 两者都缺省时，使用默认模板 base。

框架级参数

对所有模板通用，写死在服务端（src/core/params.ts）：

参数	类型	默认值	范围 / 取值	说明
template	string	base	见模板字段参考	模板名。不存在返回 404 template_not_found
width	integer	模板原生宽（无则 1200）	200 – 2400	输出宽度。底版图片类模板默认取其原生尺寸，避免拉伸
height	integer	模板原生高（无则 630）	200 – 2400	输出高度
format	enum	svg	svg | png	输出格式。SVG 跳过栅格化、更省 CPU
theme	enum	dark	dark | light	仅影响模板内部的明暗配色
debug	flag	关	debug=1 开启	开启后 Cache-Control: no-store，便于调样式

非整数 / 越界 / 非法枚举会被拒绝，返回 400 invalid_params（见错误契约）。 例如 width=12.5、width=3000、format=gif 都会报错。

模板级参数（字段）

由所选模板的 fields 元数据声明，键名即查询参数名。例如 base 有 title / subtitle， blank-1 有 heading / body / signer / date / font。

• text / textarea：受 maxLength 约束，超长返回 400。
• number：受 min / max 约束。
• select：取值必须在 options 内，否则 400。

完整清单见 模板字段参考。运行时也可调 /templates 拿到最新元数据。

响应

• 成功：HTTP 200，Content-Type: image/svg+xml 或 image/png，body 为图片字节。 另带缓存相关头（见边缘缓存）。
• 失败：非 2xx + application/json（见错误契约）。

示例

# 默认模板 + 默认 SVG
curl -L "https://og.159499.xyz/og?title=标题&subtitle=副标题" -o out.svg

# 路径指定模板 + PNG + 浅色
curl -L "https://og.159499.xyz/og/rencong-1?winner=张三&loser=李四&date=2026年9月12日&format=png" -o rc1.png

# 空白纸模板：宋体正文 + 手写落款（落款字体由模板内部决定，与 body 的 font 无关）
curl -L "https://og.159499.xyz/og/blank-2?heading=通知&body=各位同事：%0A请于周五前提交周报。&signer=张三&date=2026年9月13日&font=宋体" -o blank.svg

注意

• body 等 textarea 字段支持换行：URL 里用 %0A 表示，模板侧「换行 = 强制断行，段首自动缩进 2 字」。
• debug=1 的响应不进入边缘缓存，且带 Cache-Control: no-store，适合反复调样式。
• 同一完整 URL 幂等，可被边缘缓存复用（见边缘缓存）。