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和新的 multipartfile,规格与上传相同。 - 返回
- 更新后的文件类型和大小。媒体 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。该资源停止产生新的存储用量。