DEVELOPER GUIDE · v3.6

API 开发文档

一个预览地址覆盖 60+ 种文档格式。不用装 Office、不用转 PDF、不用维护转换队列，前端拼一个 URL 就能用。

快速开始 错误码速查
60+支持格式
1 个预览地址
16错误码
0终端插件

快速开始

更新时间：2026-04-25 v3.x REST API

无需安装 SDK 或插件，只需将文件地址拼接到预览 URL 上，即可在各类平台实现文档在线预览。

✅

支持 Word、Excel、PPT、PDF、OFD、WPS、CAD、压缩包、图片等 60+ 种格式，兼容 PC、iOS、Android、微信小程序等所有主流平台。

三步完成接入

1

准备可访问的文件地址

确保文件可通过公网 URL 访问，如 https://moxudoc.com/file/USDOC动画课件在线演示.pptx

2

拼接预览地址

将文件地址作为 src 参数附加到预览接口后面

3

打开或嵌入即可预览

在浏览器中访问拼接后的地址，或将其嵌入 iframe / webview，即可看到预览效果

接口端点

REST 
GET  https://view.moxudoc.cn/

# 最简示例：预览一个 PPT 动画课件
https://view.moxudoc.cn/?src=https://moxudoc.com/file/USDOC动画课件在线演示.pptx
ℹ️ 接口同时支持 HTTP 和 HTTPS，生产环境建议使用 HTTPS。测试文件大小建议不超过 100MB，正式环境单文件最大支持 2GB
USDOC 文档在线预览请求链路时序图：业务系统、浏览器终端、USDOC 网关与解析渲染引擎之间的五步交互
图 1：请求链路时序 —— 浏览器只与 USDOC 网关通信，解析与渲染在服务端完成

鉴权与安全

直接拼接的预览地址不经过鉴权，任何拿到地址的人都能打开。如果希望预览链接只在业务系统内有效，可以启用 AppKey 签名机制，为每个链接生成带有效期与签名的加密地址。

USDOC AppKey 签名鉴权流程：申请 AppKey、生成签名、发起请求、服务端校验四步
图 2：AppKey 签名鉴权流程 —— 签名在服务端计算，不暴露给前端
方式适用场景安全性
裸地址内网系统、公开资料、演示页面任何拿到地址的人都能访问
AppKey 签名合同、财务报表、人事档案等敏感文件地址带签名与有效期，过期自动失效
私有化部署涉密与合规要求高的场景文件全程不出企业内网
签名不要在前端计算。AppKey 的密钥只能保存在服务端，前端只接收后端生成好的完整预览地址。把密钥写进前端代码等同于公开密钥。
有效期建议：一次性查看场景设为 5–15 分钟；需要长时间停留的场景设为 2–24 小时。有效期越短越安全，过期后重新生成即可。

接口参数

所有参数均通过 GET 方式传递，拼接在请求 URL 后面。

参数名类型必填说明
srcstring必填文件地址（URL），需为公网可访问的完整地址，支持 HTTP/HTTPS
mint可选预览模式：0=超清动画 | 1=极速 | 2=SVG | 3=图文 | 4=高清(默认)
ltint可选试读页数限制，lt=2 表示仅预览前2页
watermarkstring可选水印文字，叠加在预览页面上。支持中英文及符号
formatstring可选输出格式转换，format=pdf 将文件转换为 PDF 输出
wordsstring可选文本提取，words=all 以 JSON 格式返回文档全部文字

预览模式

通过 m 参数选择不同的渲染引擎，不同模式在效果、速度和适用场景上各有侧重。

默认高清模式

不传 m 或传 m=4。顶部工具栏（打印/全屏/下载/缩放），适合大多数场景。

查看示例 →
m=1极速模式

异步按需加载，解析速度快、延迟低，适合大文件或对响应速度要求高的场景，界面精简无工具栏。

查看示例 →
m=2图文 SVG 模式

纯 HTML+SVG 渲染，像素级还原文档排版，文字可复制，适合需要精确还原样式的场景。

查看示例 →
m=3动画模式（PPT）

专为 PPT 设计，完整呈现幻灯片动画效果，支持 GIF、音视频嵌入内容播放。

查看示例 →
m=0超清模式（高级）

高保真超清渲染，版面还原精细。属于高级功能，需联系客服开通后使用。

⚠️ 超清模式属于增值功能，请联系客服（QQ：3554853473）申请开通。

模式参数示例

URL 
# 高清模式（默认，不传 m）
https://view.moxudoc.cn/?src=https://usdoc.cn/vw/demo.docx

# 极速模式
https://view.moxudoc.cn/?m=1&src=https://usdoc.cn/vw/demo.docx

# 图文 SVG 模式
https://view.moxudoc.cn/?m=2&src=https://usdoc.cn/vw/demo.docx

# PPT 动画模式
https://view.moxudoc.cn/?m=3&src=https://usdoc.cn/vw/demo.pptx

高级功能

预览水印

通过 watermark 参数叠加自定义水印文字，用于版权保护。

# watermark 参数值即为水印文字
https://view.moxudoc.cn/?watermark=仅供参考&src=https://usdoc.cn/vw/demo.docx
中文 ✓Word ✓PPT ✓Excel 暂不支持

试读页数控制

lt 参数限制预览页数，超出部分模糊处理，适用于付费阅读场景。

# 只允许预览前 2 页
https://view.moxudoc.cn/?lt=2&src=https://usdoc.cn/vw/demo.docx

转换输出 PDF

format=pdf 将 Word/PPT/Excel/OFD 等服务端转换为 PDF 返回。

# Word 转 PDF
https://view.moxudoc.cn/?format=pdf&src=https://usdoc.cn/vw/demo.docx

提取文本内容

words=all 以 JSON 格式返回文档全部文字内容，可用于全文检索、内容分析等场景。

# 提取文档中的全部文字（JSON 格式返回）
https://view.moxudoc.cn/?words=all&src=https://usdoc.cn/vw/demo.docx
ℹ️ 返回结果为 JSON 数组，每个段落作为一个字符串元素。

集成示例

根据技术栈选择合适的集成方式。

iframe 嵌入

将预览内容嵌入页面中展示，适合 OA 系统、企业内网等场景。

HTML 
<iframe
  src="https://view.moxudoc.cn/?src=https://example.com/report.docx"
  width="100%"
  height="600px"
  allowfullscreen
></iframe>

JavaScript 跳转打开

function previewDoc(fileUrl) {
  const url = 'https://view.moxudoc.cn/?src='
             + encodeURIComponent(fileUrl);
  window.open(url, '_blank');
}
// methods
previewDoc(fileUrl) {
  const url = `https://view.moxudoc.cn/?src=${encodeURIComponent(fileUrl)}`;
  window.open(url, '_blank');
}
const previewDoc = (fileUrl) => {
  const url = `https://view.moxudoc.cn/?src=${encodeURIComponent(fileUrl)}`;
  window.open(url, '_blank');
};

// JSX
<button onClick={() => previewDoc(fileUrl)>预览</button>

微信小程序集成

使用 <web-view> 组件加载预览地址。

ℹ️ 需要在微信公众平台将 view.moxudoc.cn 添加到「业务域名」白名单中。
<!-- pages/preview/preview.wxml -->
<web-view src="{{previewUrl}}"></web-view>
// pages/preview/preview.js
Page({
  data: { previewUrl: '' },
  onLoad(options) {
    const file = decodeURIComponent(options.url);
    this.setData({
      previewUrl: 'https://view.moxudoc.cn/?src=' + encodeURIComponent(file)
    });
  }
});

// 跳转时携带文件地址
wx.navigateTo({
  url: `/pages/preview/preview?url=${encodeURIComponent(fileUrl)}`
});

错误码

所有接口在出错时都会返回统一的 code 与 message 字段，HTTP 状态码与业务错误码一一对应。建议在业务侧对 42901 与 50001 做自动重试，其余错误码直接提示用户。

USDOC 文档在线预览错误码分类：请求参数类、鉴权与权限类、资源类、服务与限流类
图 3：错误码按 HTTP 状态分成四类，方便快速定位问题归属
错误码HTTP含义排查建议
40001400缺少 src 参数检查预览地址是否包含 src=
40002400文件地址格式不合法确认地址为 http/https 且已做 URL 编码
40003400参数 m 取值越界m 仅支持 0–4
40004400watermark 超出长度限制水印文本建议不超过 50 字
40101401AppKey 无效检查 AppKey 是否正确、是否已停用
40102401签名校验失败按文档重新计算签名，注意参数排序
40103401签名已过期重新生成带有效期的签名地址
40301403当前套餐不含该格式升级套餐或 联系客服
40302403域名未加入白名单在控制台配置域名白名单
40401404文件地址不可访问确认文件可公网访问且返回 200
40402404文件已被删除或移动检查源文件是否仍然存在
41301413文件超出大小上限升级套餐或先压缩文件
41501415不支持的文件格式查看 格式支持总览
42901429调用频率超出限制降低并发或申请提额，配合退避重试
42902429当日额度已用完次日自动重置，或升级套餐
50001500解析引擎内部错误建议重试；持续失败请联系技术团队
重试建议：遇到 42901 / 50001 时采用指数退避，首次等待 1 秒，之后 2、4、8 秒，最多重试 3 次。不要立即高频重试，否则会持续触发限流。

限流与配额

接口按 AppKey 维度限流，同时受「并发数」「每秒请求数」「当日调用量」三个维度约束，任一维度超限都会返回 429。不同套餐的额度不同，以控制台显示为准。

套餐单文件上限并发与调用额度
普惠版20 MB基础额度，适合个人与小团队试用
标准版40 MB适合中小业务系统日常使用
高级版80 MB适合有较高并发要求的业务系统
企业版2 GB额度可按需调整，支持私有化部署

私有化部署的限流由客户自行配置，不受云端套餐限制。需要调整云端额度时，可联系技术团队申请提额。

省额度的几个做法：同一文件地址在短时间内重复预览时，可在业务侧缓存预览结果；大文件先用 m=1 极速模式出首屏，用户翻页时再加载后续页面。

最佳实践

始终对地址做 URL 编码

文件地址里出现 &、? 或中文时会截断参数。使用 encodeURIComponent 处理后再拼接。

大文件先用极速模式

用 m=1 让用户最快看到首屏，再按需切换到高清模式，避免长时间白屏。

敏感文件加签名与水印

对合同、财报类文件启用签名有效期，并叠加带用户标识的动态水印，便于追溯泄露来源。

对 429 做退避重试

遇到限流时等待 1、2、4 秒再重试，最多 3 次，不要立即高频重发。

涉密场景用私有化

文件不适合出内网时选择私有化部署，预览服务与文件都留在企业边界内。

iframe 设置合适高度

移动端 Safari 下 iframe 需要显式高度，否则可能出现内容被截断。

支持的文件格式

分类支持格式备注
Word 文档.doc · .docx · .rtf · .dot · .wpt · .docm · .dotm高清/极速/SVG 多种模式
WPS 文档.wps与 Word 模式一致
演示文稿.ppt · .pptx · .pps · .dps支持动画模式、音视频、触发器高级动画
表格.xls · .xlsx · .csv · .et水印/转 PDF 暂不支持
PDF.pdf所有模式均支持
OFD 版式.ofd支持高清与 SVG 模式
图片.jpg · .jpeg · .png · .gif · .bmp · .webp· .emf · .wmf · .svg 直接渲染展示
压缩包.zip · .rar支持内部文件预览
文本.txt · .md · .json · .xml· .md（markdown） 代码高亮展示
图纸.dwg · .dxf · .plt高清预览，无极缩放

常见问题

文件地址需要满足什么条件？▼
如何选择预览模式？▼
预览链接可以设置有效期吗？▼
支持私有化部署吗？▼