本页内容
文件上传
通过 multipart/form-data 上传本地文件，服务会返回 Token 和可直接打开的预览地址。
上传请求
bash
curl -X POST https://preview.example.com/api/upload \
-H "X-Api-Key: ak_your_key_here" \
-F "file=@/path/to/report.xlsx" \
-F "title=季度报告" \
-F "watermark=内部资料" \
-F "expire=120"表单字段
| 字段 | 类型 | 默认/必填 | 说明 |
|---|---|---|---|
file | File | 必填 | 要预览的文件 |
title | string | 文件名 | 预览标题 |
watermark | string | 无 | 文字水印 |
watermark_image | string | 无 | 图片 URL 或 Base64 水印 |
expire | number | 0 | 有效分钟数 |
password | string | 无 | 访问密码 |
ip | string | 不限 | IP 白名单 |
max_views | number | 0 | 最大访问次数 |
toolbar | 0/1 | 1 | 显示工具栏 |
toolbar_color | string | 服务默认 | 工具栏颜色 |
background_color | string | 服务默认 | 工作区背景颜色 |
saveable | 0/1 | 1 | 允许下载 |
printable | 0/1 | 1 | 允许打印 |
copyable | 0/1 | 1 | 允许复制 |
成功响应
json
{
"token":"preview_token",
"view_url":"https://preview.example.com/view?token=preview_token",
"src":"受保护的服务端文件标识"
}文件保留与重复上传
上传接口不接受 idempotency_key，每次上传均可能创建新的 Token 并消耗配额，请勿自动重复上传。响应中的 file_expire_at（如有）表示文件保留期限；expire 控制 Token 有效期，两者分别生效，expire=0 不代表文件永久保存。
文件保留时长可通过 GET /api/key-info 的 file_ttl 查询，单位为秒。若返回 oss_warning，请结合客户中心存储配置排查；仅需打开预览时始终使用 view_url。