请求模型与参数

RenderRequest

{
  "version": 1,
  "resources": [{ "resourceToken": "<resource-token>" }],
  "layers": [],
  "output": { "format": "png", "quality": 90 }
}

字段	类型	必需	约束
version	integer	是	固定为 1
resources	array	是	1–8 项；token 不得重复
layers	array	是	0–32 项
output	object	是	最终输出格式与质量

请求执行严格白名单校验，未声明字段会返回 400 INVALID_RENDER_JOB。

ResourceReference

字段	类型	约束
resourceToken	string	43 个 base64url 字符

图层公共字段

字段	类型	默认值	约束
type	enum	无	image 或 text
zIndex	integer	0	-1000–1000
opacity	number	1	0–1，最多 4 位小数
position	object	absolute (0,0)	绝对坐标或九宫格锚点
rotation	number	0	-360–360 度
shadow	object	无	可选阴影
repeat	object	无	可选平铺

图片图层

{
  "type": "image",
  "resourceToken": "<watermark-resource-token>",
  "zIndex": 0,
  "size": { "width": 160 },
  "opacity": 0.65,
  "position": { "mode": "absolute", "x": 20, "y": 20 },
  "rotation": 0
}

字段	类型	必需	约束
resourceToken	string	是	已上传且有效的资源
size.width	integer	否	1–16384 像素
size.height	integer	否	1–16384 像素

size 出现时至少提供宽或高。只提供一个维度时保持原始宽高比；两者都提供时按指定尺寸渲染。

文字图层

{
  "type": "text",
  "text": "Markify · Internal",
  "zIndex": 10,
  "font": {
    "family": "Noto Sans CJK SC",
    "size": 48,
    "weight": 600,
    "color": "#ffffff"
  },
  "opacity": 0.65,
  "position": { "mode": "center" },
  "rotation": -20
}

字段	类型	约束
text	string	1–500 个字符
font.family	string	固定为 Noto Sans CJK SC
font.size	number	8–512 像素
font.weight	integer	100–900
font.color	string	#RRGGBB 或 #RRGGBBAA

Position

绝对坐标：

{ "mode": "absolute", "x": 20, "y": 20 }

x、y 默认为 0，单位是像素。绝对模式不能提供 offset。

锚点：

{ "mode": "bottom-right", "offset": { "x": -20, "y": -20 } }

支持：top-left、top-center、top-right、left-center、center、right-center、bottom-left、bottom-center、bottom-right。锚点模式不能提供 x、y，offset.x/y 默认为 0。

Shadow

字段	类型	默认值	约束
color	string	#000000	#RRGGBB
opacity	number	0.5	0–1
blur	number	0	0–100 像素
offsetX	number	0	-500–500 像素
offsetY	number	0	-500–500 像素

Repeat

字段	类型	必需	约束
spaceX	number	是	1–8192 像素
spaceY	number	是	1–8192 像素
stagger	boolean	否	默认 false，相邻行错位半个水平间距

间距表示相邻图层实例之间的空间，不会让实例互相覆盖。

Output

字段	类型	约束
format	enum	jpeg、png、webp
quality	integer	1–100

PNG 对质量参数的解释与有损格式不同，但仍要求提供合法值，以保持协议结构稳定。