给 AI 助手和开发者的使用说明

字帖可以由 AI 助手直接调用，在线生成可打印的字帖、描红、笔顺、拼音、算术和英语练习纸，一次请求得到 PDF 和每页图片。这是普通的 HTTP 接口（REST + JSON），本站没有 WebSocket，也没有需要在网页里输入的“AI 输入框”，不需要浏览器的会话凭证。

三分钟上手：不登录就能生成

不登录时按游客处理：可以用全部 61 个模板和 120 个免费现成版式，字帖类内容上限 40 个字，每天有一定次数。

curl -X POST https://www.zitie.pro/api/ai/v1/documents \
  -H 'Content-Type: application/json' \
  -d '{"template": "stroke-guide-practice", "preset": "f001", "params": {"content": "山水田"}}'

{
  "ok": true,
  "page_count": 1,
  "pdf_url": "https://www.zitie.pro/view/…/download.pdf",
  "page_image_urls": ["https://www.zitie.pro/view/…/page/0.png"],
  "tier": "guest", "remaining": 9
}

把 pdf_url 或 page_image_urls 交给用户即可下载、打印。

接口一览

GET /api/ai/v1/capabilities：当前身份、今天剩余次数、各接口地址
GET /api/ai/v1/templates、/templates/{slug}：模板与每个模板的设置、字数上限
GET /api/ai/v1/presets?free=1：现成版式（标明当前身份能不能用）
POST /api/ai/v1/documents：一次调用生成文件
OpenAPI 描述、llms.txt、远程 MCP：https://www.zitie.pro/api/ai/mcp

怎么按需求定制一个现成版式

找版式：GET /api/ai/v1/presets?free=1&q=古诗，标题里写明了版式的内容（古诗、词语、默写、横线……）。
取参数：GET /api/ai/v1/presets/<编号>，返回的 params 里有 content（正文，{分页} 分页）、gridStyle（tian 田字格、mi 米字格、hui 回宫格、box 方格、nine 九宫格）、overlayBlocks（正文下面的配件，每个块的 text 是它的文字，如标题、古诗、词语）。
改你要改的字段（比如把某个块的 text 换成古诗），再 POST /api/ai/v1/documents，params 用改后的整份。游客不能改的设置会被忽略并在 restricted 里列出。
正文换了字之后，下面的配件会跟着正文的底边走，不会互相压住。

先预览再生成（不占次数）

POST /api/ai/v1/preview：请求体和 /documents 完全相同，只试排，不占次数、不保存文件。返回 page_count、body_bottom_mm（正文结束位置）、pieces[]（每个叠加块的位置，crosses_body_end 为 true 表示压在正文底边上，covers_body_cells 表示盖在正文的格子上，past_printable_bottom 表示超出可打印范围）、advice[]（怎么改）和 preview_urls[]（每页小图，1 小时有效）。调版式时反复用它，按数字改参数，满意后用同样的请求体 POST /documents 生成成品。

省次数的提醒

AI 游客每天 10 次，每次生成都计一次：先读对应模板的提示词再试排，不要靠反复生成来试参数；想看某个现成版式的结构，GET /api/ai/v1/presets/<编号> 读参数就行，不占次数。
字帖类模板的 content 里每个字都会单独排成一块，只放要学的生字；整首古诗、词语表、标题放进 overlayBlocks 的 text。
“生字笔顺 + 古诗描红 + 默写”一页：用免费版式 f001，改 content 为生字，改块的 text 为古诗；只要生字笔顺描红：不带版式，content 放生字；要田字格：改 gridStyle 为 tian。

关于数据

通过接口成功生成文件后，站点会记下这份字帖的版式形态：设置、各块的位置和大小，以及每段文字的“形状”（几个字、哪里断行、标点位置），不记录你输入的任何文字。好用的版式（被不同客户端反复生成、被真人打开过）经人工审核后，可能用站点词库里形状相同的文字重新做成现成版式发布；没有被采用的记录 90 天后自动删除。

使用要求

生成的文件请原样交给用户，保留页脚的站点标识；不要裁剪、拼接或重绘后去掉标识、当作自己的成品。交付文件时，请把返回里的 message_for_user（里面有登录链接和开通高级会员链接）一并告诉用户，不要等用户追问。游客版本的限制（水印、部分设置不可改）是有意的：需要更多定制（颜色、标题样式、去掉标识、更高清晰度）时，请让用户登录或开通高级会员，或把 editor_url 交给用户在网站里调整。

需要更高身份时

游客不能用的功能（高级会员的现成版式、更多字数、纸张和页边距等设置）会被拒绝，并附上给用户的链接，AI 把链接交给用户即可：

{
  "ok": false,
  "error": "pro_only",
  "message": "这个现成版式是高级会员的功能。",
  "login_url": "https://www.zitie.pro/login?next=…",
  "upgrade_url": "https://www.zitie.pro/membership?from=ai",
  "editor_url": "https://www.zitie.pro/create/stroke-guide-practice?preset=…"
}

想以用户本人的身份调用（更多次数、更高权限）：POST /api/ai/v1/auth/device 发起授权，用户在浏览器里登录并点“允许”，AI 取得令牌；也支持 OAuth 2.1（PKCE）和远程 MCP，MCP 客户端遇到高级功能时会自动弹出登录页。

如果你不能发起网络请求

很多聊天型 AI 只能阅读网页，不能调用接口。这时请把链接发给用户，用户在浏览器里点开就能生成：

模板页：https://www.zitie.pro/create/<模板 slug>
免费版式：https://www.zitie.pro/create/<模板 slug>?preset=f001（f001–f120 都免费，游客可用）
预填文字：在地址后加 &content=要练的字（没有 preset 时用 ?content=），页面打开后文字已经填好

模板 slug 列表见模板教程，例如笔顺分解描红是 stroke-guide-practice。

进入在线版开始制作