渲染 API
让卡片创作，接入你自己的工作流。
从文字到图片，只需一个请求
接口与编辑器共用同一套渲染。支持扁平 JSON、嵌套 JSON，以及完整文档模型；兼容入口返回 PNG，完整文档入口还支持其他图片格式、PDF 与 ZIP。
/api/saveImg用于兼容旧参数；/api/render接受完整文档与导出设置。将示例中的 BASE_URL 换成当前部署地址。
请求示例
curl -X POST "$BASE_URL/api/saveImg" \
-H "Content-Type: application/json" \
--data '{"temp":"tempA","form":{"title":"把想法，留在一张卡片里","content":"<p>文字值得被认真对待。</p><p>给它一点留白，让分享动人。</p>","author":"来张创作室"},"style":{"width":440,"height":620,"padding":32,"fontSize":18,"color":"#e1e2f3","textColor":"#263041"},"switchConfig":{"showTitle":true,"showContent":true,"showAuthor":true},"imgScale":2}' \
--output card.png主要参数
| 字段 | 类型 | 说明 |
|---|---|---|
| temp | string | 模板家族，例如 tempA、tempJin、tempCode |
| form | object | 标题 title、正文 content、作者 author、日期 date 等 |
| style | object | 宽高、字号、背景、文字与强调色等样式 |
| switchConfig | object | 字段显示控制，使用布尔值 |
| format | string | 完整文档入口支持 png、jpeg、webp、pdf；兼容入口固定 PNG |
| scale / imgScale | number | 完整文档用 scale；旧兼容入口用 imgScale，范围 0.5–4 |
| document | object | 完整 CardDocument，供 /api/render 使用 |
| mode | string | single 单张、zip 批量、collage 拼图、pdf 文档 |
| paper / fit | string | PDF 纸型 a4/a3/letter/legal；适配 fit/fill |
扁平结构将 title、content、width 等字段放在顶层。嵌套结构使用 form、style 与 switchConfig。两处同时提供同一字段且值不同，会返回参数冲突错误，请只保留一种明确写法。
字段参考
内容 form
| title / content | 标题与正文 HTML；完整文档可将 contentFormat 设为 markdown |
| author / date / foreword | 作者、日期与前言 |
| translate / signature | 译文与签名 |
| icon / cover | 头像与封面；使用当前部署上传后的素材地址 |
| qrcode / qrcodetitle / qrcodetext | 旧结构二维码地址、标题与提示；完整文档使用 qrCode、qrCodeTitle、qrCodeText |
样式 style
| width / height | 宽 240–2400；固定高 100–5000，0 为自动高度 |
| padding / fontSize / lineHeight | 内边距、基础字号、行高；数字可使用 px 字符串 |
| color / textColor | 兼容结构的背景与文字颜色；完整文档使用 background / foreground |
| borderRadius / backShadow | 兼容结构圆角与阴影；完整文档使用 radius / shadow |
| font / fontScale / fonts | 字体、整体倍率、字段倍率；完整文档字段倍率为 fieldSizes |
| align / letterSpacing | left / center / right / justify 与字间距 |
显隐 switchConfig
| showTitle / showContent | 标题与正文 |
| showDate / showAuthor / showIcon | 日期、作者与头像 |
| showForeword / showTranslation / showSignature | 前言、译文与签名 |
| showQRCode / showTextCount / showPageNum / showWatermark | 二维码、字数、页码与来张卡片水印；全部使用布尔值 |
完整文档的每张 cards[i] 包含 id、name、form、style、visibility、contentFormat。旧结构使用 switchConfig；完整文档使用 visibility。上传素材先调用 /api/assets，将返回的 url 放入图片字段。
模板与布局
| 名称 / temp | subTempId / layoutId |
|---|---|
| 日常 tempA | tempA（留白）、tempA2（轻盈） |
| 透明 tempC | tempC（透明） |
| 金句 tempJin | tempJin（引言）、tempJinB（落款居中）、tempJinC（头像落款） |
| 书摘 tempB | tempB（书页）、tempCalendar（日历） |
| 便当 tempEasy | tempEasy（内容盒） |
| 备忘 tempMemo | tempMemo（手记） |
| 黑日 tempBlackSun | tempBlackSun（黑日） |
| 框界 tempE | tempE（边框） |
| 代码 tempCode | tempCode（终端） |
| 海报 tempPoster | tempPoster（大字报） |
| 简约 tempMH | tempMH（素笺） |
| 故事 tempStory | tempStory（故事）、tempStory2（通栏封面） |
| 手写 tempWrite | tempWrite（手写信笺） |
| 图片 tempD | tempD（图片画布） |
| 对话 tempChat | tempChat（气泡） |
| 生活纸品 tempPaper | paperTravel（旅行票根）、paperReceipt（情绪小票）、paperGallery（私人展签） |
| 趣味卡 tempPlay | playReveal（祝福揭晓）、playFlip（双形态闪卡）、playCutout（出框拍立得） |
工作区接口
工作区接口使用登录 Cookie 或 API 密钥。成功响应为 {data: ...}，失败为 {error: {code, message}}。所有 ID 均为 UUID，私有数据由服务端校验归属。
| 路径 | 方法与用途 |
|---|---|
| /api/auth | GET 当前用户；POST action: local / register / login / logout |
| /api/documents | GET 草稿列表（q、tag、deleted）；POST {document} 创建 |
| /api/documents/[id] | GET 单项；PUT {document,revision} 保存；DELETE 软删除；PATCH {action:"restore"} 恢复 |
| /api/documents/[id]/versions | GET 历史列表；POST {versionId,revision} 恢复指定版本 |
| /api/styles | GET 列表；POST {name,templateId,style,visibility} 保存样式 |
| /api/assets | GET 列表；POST multipart 字段 file 上传 |
| /api/community | GET 社区列表；POST {documentId,title,description,tags} 发布 |
| /api/shares | GET 分享记录；POST {documentId,expiresInDays} 创建；DELETE {id} 撤销 |
| /api/settings | GET 偏好、能力、订单；PUT {settings} 保存偏好 |
保存草稿需附带上次读取的 revision。发生 409 VERSION_CONFLICT 时先重新读取，避免覆盖其他窗口保存的内容。列表响应 data 为数组，单项响应 data 为对象。
响应与异常
| HTTP 状态 | 处理建议 |
|---|---|
| 200 | 先检查 Content-Type，再作为文件保存。图片应为 image/*，PDF 应为 application/pdf，批量文件为 application/zip。 |
| 400 / 422 | JSON、字段类型、尺寸或参数冲突不正确，修正输入后重试。 |
| 413 | 请求内容或导出尺寸过大，减少内容或渲染倍率。 |
| 429 | 当前请求过密，短暂等待后有限重试，避免循环立即重发。 |
| 500 / 503 / 504 | 渲染服务暂不可用或超时；记录错误，最多有限重试。 |
{
"error": {
"code": "INVALID_INPUT",
"message": "请提供有效的 JSON 参数"
}
}常见错误码：INVALID_JSON、INVALID_INPUT、INVALID_MODE、INVALID_SELECTION、RESOURCE_NOT_ALLOWED、RESOURCE_LOAD_FAILED、RATE_LIMITED、RENDER_BUSY、RENDER_TIMEOUT、PIXEL_LIMIT、CARD_LIMIT、PAYLOAD_TOO_LARGE。
不要把错误响应直接当作图片。设置请求超时，校验内容类型与文件大小，重试时保留原始参数。