Token API · 预览权限、有效期与幂等

本页内容

创建 Token

请求

http

POST https://preview.example.com/api/token
X-Api-Key: ak_your_key_here
Content-Type: application/json

{
  "src":"https://example.com/report.docx",
  "idempotency_key":"order-file-20260803-001",
  "title":"季度报告",
  "watermark":"内部资料",
  "expire":60,
  "printable":false
}

Body 参数

参数	类型	默认/必填	说明
`src`	string	必填	可公开下载的 HTTP/HTTPS 文件地址
`idempotency_key`	string	必填	1–255 字符，同一 API Key 内的稳定业务标识；满足复用条件时返回已有 Token
`title`	string	文件名	预览标题
`watermark`	string	无	文字水印
`watermark_image`	string	无	图片 URL 或 Base64 水印
`expire`	integer	0	Token 有效分钟数；0 不限制 Token 时间，但仍受撤销、文件状态和 API Key 状态限制
`password`	string	无	访问密码
`ip`	string	不限	逗号分隔 IP 白名单
`max_views`	integer	0	最大访问次数，0 表示不限
`limit`	integer	0	支持分页限制的渲染器最多展示页数，0 不限制；不是所有格式都支持
`toolbar`	boolean	true	是否显示工具栏
`toolbar_color`	string	服务默认	工具栏背景色，格式为 #RRGGBB
`background_color`	string	服务默认	预览工作区背景色，格式为 #RRGGBB
`saveable`	boolean	true	是否允许下载
`printable`	boolean	true	是否允许打印
`copyable`	boolean	true	是否允许复制

成功响应与打开预览

响应

json

{
  "token":"preview_token",
  "view_url":"https://preview.example.com/view?token=preview_token"
}

iframe

html

<iframe src="https://preview.example.com/view?token=preview_token" width="100%" height="720" title="文档预览"></iframe>

使用与错误处理

成功响应的 idempotent: true 表示复用了已有 Token。创建成功不代表文件已经下载或转换完成，首次打开预览时仍可能等待文件准备。不要通过反复创建 Token 催促转换。

收到 429 时区分额度耗尽、每日限额和请求限速；只有可重试错误才按返回提示重试。其他错误请查看错误与排查。关闭下载、打印或复制入口是页面权限控制，无法阻止查看者截屏。