API 文档

API 参考

在服务端使用 Authorization: Bearer <项目密钥>。JSON 请求体通常最多 1 MiB,/layout/paginate 支持 4 MiB。浏览器使用带令牌的分享链接或表格短期凭证。

文字处理、托管媒体上传和替换、表格创建和写行可带 Idempotency-Key。同键重试请沿用原请求。请求变化或仍在处理时会返回 409。

当前免费 · 额度内调用费用为零,用量照常记录。各项目共用同一账号的额度。

文字用量按 Unicode 码点统计。超出当月免费用量时返回 429 和 developer_free_quota_exceeded。错误正文含 error.code 和 error.message。

按原版式批量重排

一套多字段设计可以放入长短不同的文案。正文高度变化时,下方字段仍沿用原间距,每行返回可编辑的 HTML。

用多行新内容重排同一版式

POST/api/developer/v1/layout/reflow
请求
提交版式 html、设计宽度 designWidth(像素)和 rows。每行提供唯一 id 和以字段编号为键的 content。也可用预先测量得到的 template 代替 HTML 和宽度。
返回
按行返回 id、连续可编辑的 html、实测高度 height 和分页用的 layout。可选 pageHeight 仅开启超高提示 overflow。

预先测量可复用的模板(可选)

POST/api/developer/v1/layout/finalize-contract
请求
传入带字段编号的 html 和 designWidth。
返回
保存响应中的 template,以后可交给重排接口复用。

用行内样式设置各字段的位置和宽度,用 data-mp-field 标记字段,data-mp-fixed 标记固定装饰。一次可提交 1–200 行。图片支持内嵌 PNG、JPEG 和 WebP。

将重排结果分页为 PDF

需要打印时,将一行重排结果交给 Magic Press 的打印引擎,得到带页眉、页脚和续排的 PDF。

从连续 HTML 生成 PDF

POST/api/developer/v1/layout/paginate
请求
传入同一条重排结果的 html 和 layout。可用 page.heightMm 指定纸高,page.marginsMm 按上、右、下、左指定页边距。可选 header 和 footer 位于 page 内,支持 {{pageNum}} 和 {{totalPages}}。
返回
返回 PDF 的 Base64 编码 pdfBase64、mediaType 和页数 pageCount。原来的 HTML 可继续编辑或交给自己的打印引擎。

按模板批量排版

将自有 HTML 模板应用到最多 200 条记录,每条都沿用同一版式。改一条只需重排这一条。

按模板渲染多行

POST/api/developer/v1/layout/template-batch
请求
JSON。必填 template(version: 1、html、fields)和 rows。每行含唯一 id 和与模板字段完全匹配的 content,字段值使用纯文本。每次 1–200 行,合计最多 1,000,000 字符。
返回
rows 中每项包含 id 和 html,另有 characterCount 和 operationId。每个字段可通过 data-mp-field 定位。

也可自建模板。每个 {{MP:fieldName}} 占位符在 HTML 文本节点中出现一次。服务端复用模板直接渲染本次输入的行。

按示例批量整理文案

给一组原稿和整理好的字段,AI 按同样的写法整理其余文案。返回的字段可直接套用你的模板。

从多条原稿生成同一组字段

POST/api/developer/v1/content/normalize-batch
请求
JSON。必填 example.source(示例原稿)、example.content(1–20 个已整理的文字字段)和 rows(1–50 条,每条含唯一 id 和原文 source)。可选 instructions,例如统一使用 24 小时制。输入合计最多 20,000 字符。
返回
按输入顺序返回 rows,每条含原 id 和与示例同名的 content 字段,缺失值为空字符串。另有 operationId 和 characterCount。

整理示例定义字段和文字风格。把返回的行交给含同名字段的 HTML 模板即可排版,两步各自记录用量。已有整理好的字段可直接调用批量排版。

长文分栏与分页

让不同长度的章节接续排入同一份单栏或双栏文档,得到可打印的整本文稿。

生成分页 HTML

POST/api/developer/v1/layout/publication
请求
JSON。提交文档 title 与 1–200 个 sections,每节含唯一 id、heading 和纯文本数组 paragraphs。可选 language(en 或 zh-CN)及 template,支持 A4/A5、单栏或双栏、页边距、栏距、字号和强调色。最多 100,000 个输入字符。
返回
返回完整可打印网页 html、页数 pageCount、按页列出章节编号的 pages、characterCount 和 operationId。在浏览器中打开 HTML,即可打印或另存为 PDF。

默认 A4 双栏。正文按浏览器实测高度续栏、续页。文档标题、各节标题和正文按输入字符计量一次。

AI 设计

需要新视觉风格时,用首条内容和设计要求生成 HTML,再复用返回的模板。

生成设计

POST/api/developer/v1/layout/ai-design
请求
JSON。必填 content,可传一段文字或 1–100 个文本字段。可选 requirements 描述设计要求,最多 10,000 个 UTF-16 代码单元。内容和要求合计 1–100,000 字符。
返回
html、template、characterCount 和 operationId。把 template 传给批量排版接口即可复用。

固定坐标排版

文字自动缩到框内可容纳的最大字号,框的位置和大小保持原样。

排版指定页面和框

POST/api/developer/v1/layout/fixed
请求
JSON。必填 page(width、height)、frames(id、type、left、top、width、height)、rows(id、按框 ID 对应内容的 values)。每次 1–100 个框、1–200 行,最多 1,000,000 字符。
返回
rows 内每项包含 id、html 和文字框尺寸测量(frameId、scale、fontSizes),另有 fonts、imageLoading、characterCount、operationId。

使用 CSS 像素。框可带 rotation。文字框可配置字体、字号、颜色、粗细、斜体、对齐、行高,以及 runStyles 或 ranges。图片框填 HTTPS 图片地址,选择 fit: "cover" 或 "contain",图片由渲染页面加载。

Word 转 HTML

提取正文、嵌入图片、表格和支持的 Word 公式,生成流式网页内容。

上传 DOCX

POST/api/developer/v1/documents/docx-to-html
请求
multipart/form-data。必填 file,非空 .docx,最多 10 MiB。
返回
html、assets、stylesheetUrl、warnings、characterCount、documentId、resultUrl 和 previewUrl。嵌入 HTML 时加载返回的样式表以显示公式。

读取或删除转换结果

GETDELETE/api/developer/v1/documents/results/{id}
请求
原项目的 API 密钥和路径中的 documentId。
返回
GET 返回与转换接口同结构的结果。 DELETE 删除结果和素材并返回 204,原分享地址随即失效。

打开网页预览

GET/api/developer/v1/documents/public/{id}
请求
直接打开 previewUrl,其中包含 token。
返回
可在浏览器打开的 HTML 网页。

读取提取的图片

GET/api/developer/v1/documents/public/{id}/assets/{assetId}
请求
使用 assets[].url 中的完整地址及其 token。
返回
图片文件。读取按传输字节计量。

分栏、双面分页和浮动图文在网页中可能变化,请查看 warnings。预览和素材分享链接保留期间没有固定过期时间,持有完整链接即可访问。保留的结果和素材按存储时间计量。

音视频二维码

上传音视频获得播放链接和二维码,替换托管文件时沿用原码。

上传托管文件

POST/api/developer/v1/media
请求
multipart/form-data。必填 file。支持 MP3、M4A、WAV、OGG、MP4、WebM,最多 50 MiB。
返回
mediaId、kind、bytes、playbackUrl、qrCodeDataUrl 和 hosted: true。

为自有播放地址生成二维码

POST/api/developer/v1/media
请求
JSON。必填 playbackUrl,最长 1,024 字符的 HTTPS 地址,网址中不能有用户名或密码。
返回
playbackUrl、qrCodeDataUrl 和 hosted: false。二维码直接指向原网址,由你的服务托管和更新内容。

替换托管文件

PATCH/api/developer/v1/media/{id}
请求
原项目密钥、路径中的 mediaId 和新的 multipart file,规格与上传相同。
返回
更新后的文件类型和大小。媒体 ID、播放地址和二维码沿用原值。

删除托管文件

DELETE/api/developer/v1/media/{id}
请求
原项目密钥和路径中的 mediaId。
返回
返回 204。原播放链接和二维码失效,停止累积该文件的存储用量。

打开播放页

GET/api/developer/v1/media/{id}/play
请求
打开返回的 playbackUrl,其中包含 token。
返回
可在浏览器播放的页面。

播放文件内容

GETHEAD/api/developer/v1/media/{id}/content
请求
使用播放页中的完整文件链接和 token,可传单个字节区间的 Range。
返回
媒体字节流或响应头。GET 按实际传输计量。

完整播放地址就是分享链接,保留文件期间没有固定过期时间。托管文件按存储大小和时间、实际传输字节计量,余额不足可能中断播放。

嵌入多维表格

在你的产品里,让用户把 Word 或带文本层的 PDF 粘进单元格,用 AI 列生成纯文本或 HTML,并纵向填充多行。

签发嵌入凭证

POST/api/developer/v1/tables/embed-credentials
请求
JSON。必填你系统中的 customerId 和 userId,各最多 128 字符。服务器从当前登录会话取得客户与用户身份。
返回
embedUrl、token、expiresAt、projectId 和 customerId。凭证有效期 5 分钟。浏览器用 SDK 的 mountTable 嵌入,并通过你的服务端续期。

核对短期凭证

GET/api/developer/v1/tables/embed-credentials
请求
提交 Authorization: Bearer <token>,此处使用短期嵌入凭证。
返回
projectId、customerId、userId 和 expiresAt。签发密钥被撤销后,关联凭证也会失效。

列出客户表格

GET/api/developer/v1/tables
请求
查询参数必填 customerId,可选 after。
返回
tables 和 nextCursor,每页最多 100 张表。

创建表格

POST/api/developer/v1/tables
请求
查询参数必填 customerId。JSON 必填 name(最多 160 字符)和 columns(1–40 个非空列名,各最多 120 字符)。
返回
返回 201 和 id、name、columns。列初始类型为文本。

读取工作表

GET/api/developer/v1/tables/{id}
请求
必填表格 id 和查询参数 customerId。可选 sheet 和 offset 从 0 开始,limit 为 1–100,默认 50。
返回
sheets、columns、rows、totalRows 等。行内 cells 按列 ID 索引。

追加或更新行

PATCH/api/developer/v1/tables/{id}
请求
必填表格 id 和查询参数 customerId。JSON 必填 sheetId 和 1–30 条 rows。每条含 cells,按列 ID 存字符串、数字、布尔值或 null。带行 id 则更新,省略则追加。
返回
appendedRowIds 和 edits。

读取表格附件

GETHEAD/api/developer/v1/table-assets/{id}
请求
使用嵌入表格返回的完整附件链接和 token。
返回
附件字节流或响应头。GET 按实际传输计量。

数据按项目及客户隔离,同一客户内的用户共用工作区,无需在 Magic Press 注册。使用 SDK 的 mountTable({ locale: "en", ... }) 可指定英文界面,默认跟随宿主页或浏览器的语言。编辑器支持 Word、PDF 粘贴,以及 AI 列的 HTML、纯文本和纵向填充。AI 列使用表格中配置的模型密钥。表格按存储和传输计量。

资源查询与清理

按项目查看存储资源并删除不再保留的内容。

列出项目资源

GET/api/developer/v1/resources
请求
项目密钥,可选查询参数 after。
返回
resources 和 nextCursor。每页最多 100 项,包含媒体、文档、表格与附件等,bytes 以字符串返回。

删除存储资源

DELETE/api/developer/v1/resources/{id}
请求
原项目的密钥和资源列表返回的 id。
返回
返回 204。该资源停止产生新的存储用量。