端点
| 方法 | 路径 | 说明 | Scope |
|---|---|---|---|
GET | /v1/capabilities | 平台、导出物、限制与 MCP 工具清单(公开,无需认证) | — |
GET | /v1/themes | 主题目录(36 套,仅元数据,不含样式源码)(公开) | — |
POST | /v1/projects | 创建项目(markdown + title),返回 project_id / 结构检测 / open_in_zhangyu_url | project:write |
GET | /v1/projects | 列出当前用户的项目(不含正文) | project:read |
GET | /v1/projects/{id} | 读取项目(含正文) | project:read |
POST | /v1/analyze | 分析内容:预计页数、违禁词、版式风险、平台限制 | project:read |
POST | /v1/renders | 提交渲染 Job(xhs / wechat / twitter),202 + render_id | render:create |
GET | /v1/renders/{id} | 查询渲染状态、产物清单、签名预览 URL | render:read |
POST | /v1/renders/{id}/cancel | 取消排队/执行中的渲染 | render:create |
POST | /v1/shares | 创建私密分享链接(默认不含正文,noindex) | share:create |
GET | /v1/renders/png-canvas/{id} | PNG 画布页(签名访问,server PNG 截图输入) | signature |
GET | /v1/usage | 当前周期用量与配额 | usage:read |
POST | /v1/tokens | 创建 Personal Access Token(需 tokens:write) | tokens:write |
GET | /v1/tokens | 列出 token(仅前缀,不含 secret) | tokens:write |
DELETE | /v1/tokens/{id} | 撤销 token | tokens:write |
渲染 Job
POST /v1/renders 立即返回 202 与 render_id(status=queued);执行由服务端调度,轮询 GET /v1/renders/{id} 直到 completed / failed。产物以私有资产存储,预览 URL 为带过期时间的签名链接,HTML 产物以沙箱 CSP 提供。
open_in_zhangyu_url
所有渲染与项目响应都带此链接:用户点击后在章鱼排版编辑器中载入同一项目,可继续精调并导出成品(PNG ZIP 等)。
示例:三平台渲染
curl -X POST https://zhangyupaiban.com/api/v1/renders \
-H "Authorization: Bearer zyp_…" \
-H "Idempotency-Key: demo-render-001" \
-H "Content-Type: application/json" \
-d '{"project_id":"prj_…","platform":"xhs","config":{"aspect_ratio":"3:4"}}'