96doc文档预览服务
    • 96DOC 文件在线预览服务与接入说明
    • 生成预览链接
      POST
    • 清除缓存/查询有效期
      POST
    • 上传本地文件
      POST

      生成预览链接

      POST
      /api/preview
      创建或复用预览任务，返回 id、status、previewURL 和 htmlURL。HTTP 202 表示任务已受理，status=ready 表示转换完成。
      url、filename、mtime、referer、pdf、key 和 options 是请求体顶层字段；阅读设置放在 options 内，水印样式放在 options.stampStyle 内。只有 url 必填，其余字段可选。
      接口密钥在服务配置 KEY 非空时需要提供，推荐使用 X-Preview-Key 请求头。常规接入直接打开 previewURL；需要保护源地址的业务使用 htmlURL。
      预期 HTTP 202。
      返回 202 表示接受请求。常规业务直接打开 previewURL；自制阅读器需轮询任务。KEY 非空时使用请求头。有效缓存与分享规则存续期间，相同入参复用相同 previewURL 和 htmlURL；不会延长有效期，也不会重置一次性访问。缓存清除或缓存到期后重新生成的 htmlURL 会变化。

      JSON Body 参数说明#

      参数类型说明
      urlstring完整原始文件 HTTP/HTTPS 地址，JSON 中不要再次 URL 编码
      filenamestring地址无后缀时指定文件名
      mtimestring文件修改标记，可填秒级时间戳或日期字符串。源 URL 不变时更新此值会重新下载并生成新缓存；值不变继续复用。最多 256 字节
      refererstring读取源文件时发送的 Referer 请求头，用于源站防盗链。HTTP/HTTPS 地址，最长 2048 字节；不改变源地址白名单与 SSRF 校验
      pdfboolean表格同时转换 PDF；Office/PDF 文件本来就走 PDF 读取路径
      optionsobject预览模式、工具栏显示、水印与访问规则。未提供的字段使用默认值
      options.displayModestringPDF 精准模式或图片模式；两者均上下连续阅读
      options.allowPrintboolean打印权限：关闭时禁用本页打印样式并隐藏入口。showPrint 单独控制显示；不是 DRM
      options.allowCopyboolean精准模式允许文字选择/复制；图片模式没有文字层，体验页隐藏复制选项；不是 DRM
      options.allowDownloadboolean允许下载原文件；设置页数限制时仍禁止原文件下载
      options.showToolbarboolean显示工具栏
      options.oneVisitboolean首次 GET 顶层 HTML 消耗一次访问；再次打开或刷新被拒绝，当前页面的资源请求继续可用
      options.headingstring自定义页签标题；最多 512 UTF-8 字节
      options.validMinutesinteger分享规则有效分钟数；0 为永久，和转换缓存期限独立
      options.maxPagesinteger仅开放前 N 页；0 不限制，精准模式同样支持；适用于分页文件
      options.fontSizeinteger文本与工作表字号；不改变 PDF 原始字号；0 使用默认 14，水印字号使用 stampStyle.fontSize；非 0 时仅允许 6–58
      options.ipAllowstring允许的 IP/CIDR，逗号分隔；空为不限制，最多 1000 UTF-8 字节
      options.openCodestring访问密码；最多 128 UTF-8 字节，不返回、不放入分享 URL
      options.stampModestring水印类型，显示层水印
      options.stampTextstring水印文字，最多 1000 UTF-8 字节
      options.stampImagestring允许域名上的图片 URL 或 data:image/...;base64,...；PNG/JPG/GIF 最大 1MB/400万像素；image 模式必填
      options.stampStyleobjectcustom 水印的完整样式；含独立字号、旋转、透明度、颜色、平铺与间距
      options.stampStyle.fontSizeinteger独立水印字号；0 使用默认 24
      options.stampStyle.angleinteger旋转角度
      options.stampStyle.opacitynumber水印透明度：0.05 最淡，1 不透明
      options.stampStyle.colorstring六位十六进制颜色
      options.stampStyle.tileboolean是否平铺
      options.stampStyle.gapinteger平铺间距
      options.showThumbnailsboolean显示缩略图；未传默认显示。手机端打印与全屏始终隐藏。
      options.showSearchboolean显示查找；未传默认显示。手机端打印与全屏始终隐藏。
      options.showPagingboolean显示翻页按钮及页码；未传默认显示。手机端打印与全屏始终隐藏。
      options.showZoomboolean显示缩放按钮及选择框；未传默认显示。手机端打印与全屏始终隐藏。
      options.showPresentationboolean显示演示模式；未传默认显示。手机端打印与全屏始终隐藏。
      options.showPrintboolean显示打印按钮；未传默认显示。手机端打印与全屏始终隐藏。
      options.showDownloadboolean显示原文件下载按钮；未传默认显示。手机端打印与全屏始终隐藏。
      options.showFullscreenboolean显示全屏；未传默认显示。手机端打印与全屏始终隐藏。
      options.downloadPlacementstring下载按钮位置；allowDownload 控制下载权限。floating 在右下角显示。
      keystring配置 KEY 非空时可在 JSON 传入；推荐使用 X-Preview-Key 请求头

      请求参数

      Header 参数

      Body 参数application/json必填

      示例
      {
    "url": "http://www.96doc.com/demo/sample-v2.docx",
    "options": {
        "displayMode": "precise",
        "allowPrint": true,
        "allowCopy": true,
        "allowDownload": true,
        "showToolbar": true,
        "oneVisit": false,
        "heading": "",
        "validMinutes": 0,
        "maxPages": 0,
        "fontSize": 14,
        "ipAllow": "",
        "openCode": "",
        "stampMode": "none",
        "stampText": "",
        "stampImage": "",
        "stampStyle": {
            "fontSize": 24,
            "angle": -24,
            "opacity": 0.5,
            "color": "#aaaaaa",
            "tile": true,
            "gap": 240
        }
    },
    "filename": "sample-v2.docx",
    "mtime": "",
    "pdf": false
}

      请求示例代码

      Shell
      JavaScript
      Java
      Swift
      Go
      PHP
      Python
      HTTP
      C
      C#
      Objective-C
      Ruby
      OCaml
      Dart
      R
      请求示例请求示例
      Shell
      JavaScript
      Java
      Swift
      curl --location 'http://47.114.97.73:8088/api/preview' \
--header 'X-Preview-Key: {{key}}' \
--header 'Content-Type: application/json' \
--data '{
    "url": "http://www.96doc.com/demo/sample-v2.docx",
    "options": {
        "displayMode": "precise",
        "allowPrint": true,
        "allowCopy": true,
        "allowDownload": true,
        "showToolbar": true,
        "oneVisit": false,
        "heading": "",
        "validMinutes": 0,
        "maxPages": 0,
        "fontSize": 14,
        "ipAllow": "",
        "openCode": "",
        "stampMode": "none",
        "stampText": "",
        "stampImage": "",
        "stampStyle": {
            "fontSize": 24,
            "angle": -24,
            "opacity": 0.5,
            "color": "#aaaaaa",
            "tile": true,
            "gap": 240
        }
    },
    "filename": "sample-v2.docx",
    "mtime": "",
    "pdf": false
}'

      返回响应

      🟢202
      application/json
      创建或复用预览任务
      Bodyapplication/json

      示例
      {
    "id": "string",
    "name": "string",
    "kind": "office",
    "status": "queued",
    "error": "string",
    "createdAt": "2019-08-24T14:15:22.123Z",
    "expiresAt": "2019-08-24T14:15:22.123Z",
    "linkExpiresAt": "2019-08-24T14:15:22.123Z",
    "size": 0,
    "pdfAvailable": true,
    "pageImages": [
        {
            "number": 0,
            "width": 0,
            "height": 0
        }
    ],
    "sourceDigest": "string",
    "options": {
        "displayMode": "precise",
        "allowPrint": true,
        "allowCopy": true,
        "allowDownload": true,
        "showToolbar": true,
        "heading": "string",
        "maxPages": 0,
        "fontSize": 14,
        "stampMode": "none",
        "stampText": "string",
        "stampStyle": {
            "fontSize": 24,
            "angle": -24,
            "opacity": 0.5,
            "color": "#aaaaaa",
            "tile": true,
            "gap": 240
        },
        "showThumbnails": true,
        "showSearch": true,
        "showPaging": true,
        "showZoom": true,
        "showPresentation": true,
        "showPrint": true,
        "showDownload": true,
        "showFullscreen": true,
        "downloadPlacement": "toolbar",
        "access": "string",
        "stampAsset": true
    },
    "previewURL": "string",
    "htmlURL": "string",
    "parentId": "string"
}
      🟠400
      🟠401
      🟠403
      🟠405
      🟠413
      🟠429
      🔴503
      修改于 2026-10-12 13:24:46
      上一页
      96DOC 文件在线预览服务与接入说明
      下一页
      清除缓存/查询有效期
      Built with