API 概览

快速开始

PreviewFile.dev 提供简单的 REST API，可从 URL 生成预览链接。只需一次调用就能创建安全、带有效期的预览链接。

支持 110+ 文件格式：预览 PDF、Office 文档、图片、视频、代码文件等。完整列表见支持的格式。

POST /api/u

从 URL 创建预览链接：

curl -X POST https://previewfile.dev/api/u \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "url": "https://example.com/document.pdf",
    "ttlMinutes": 120,
    "watermark": "Confidential",
    "noDownload": true,
    "oneTime": false
  }'

返回示例：

{
  "success": true,
  "data": {
    "shortUrl": "a1b2c3d4",
    "previewUrl": "https://previewfile.dev/p/a1b2c3d4",
    "expireAt": "2025-10-02T15:30:00Z",
    "status": "READY",
    "ttlMinutes": 120,
    "watermark": "Confidential",
    "noDownload": true,
    "oneTime": false
  }
}

API 会使用 nanoid(8) 自动生成短链，兼顾安全性与可读性。

API 参考

认证

在 x-api-key 请求头中包含你的 API Key：

x-api-key: YOUR_API_KEY

稳定版本 OpenAPI（`/api/v1`）

长期集成建议使用版本化接口：

OpenAPI schema：GET /api/v1/openapi.json
上传文件（multipart）：POST /api/v1/upload
获取预览元数据：GET /api/v1/previews/{shortUrl}
获取文件访问地址（直链或 S3 presigned）：GET /api/v1/previews/{shortUrl}/file-url

上传示例

curl -X POST https://previewfile.dev/api/v1/upload \
  -H "x-api-key: $API_KEY" \
  -F "file=@./document.pdf" \
  -F "ttlMinutes=60" \
  -F "watermark=Confidential" \
  -F "noDownload=true" \
  -F "oneTime=false"

获取文件访问 URL

curl -X GET https://previewfile.dev/api/v1/previews/a1b2c3d4/file-url \
  -H "x-api-key: $API_KEY"

请求参数

字段	类型	必填	默认值	说明
`url`	`string`	是	-	要预览的原始 URL
`ttlMinutes`	`number`	否	`60`	链接有效期（分钟）（5-1440）
`watermark`	`string`	否	`null`	水印文本（最多 120 字符）
`noDownload`	`boolean`	否	`false`	禁用下载
`oneTime`	`boolean`	否	`false`	首次访问后即过期

响应

成功响应 (200)：

{
  "success": true,
  "data": {
    "shortUrl": "a1b2c3d4",
    "previewUrl": "https://previewfile.dev/p/a1b2c3d4",
    "expireAt": "2025-10-02T15:30:00Z",
    "status": "READY",
    "ttlMinutes": 120,
    "watermark": "Confidential",
    "noDownload": true,
    "oneTime": false
  }
}

响应字段：

字段	类型	描述
`shortUrl`	`string`	8 位短链接标识符
`previewUrl`	`string`	可分享的完整预览 URL
`expireAt`	`string`	ISO 8601 过期时间戳
`status`	`string`	预览状态：`READY`、`PENDING` 或 `EXPIRED`
`ttlMinutes`	`number`	链接有效时长
`watermark`	`string \| null`	已配置时的水印文本
`noDownload`	`boolean`	下载限制状态
`oneTime`	`boolean`	一次性访问限制

错误响应 (4xx/5xx)：

{
  "success": false,
  "error": "错误信息"
}

使用示例

cURL

curl -X POST https://previewfile.dev/api/u \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "url": "https://example.com/document.pdf",
    "ttlMinutes": 120,
    "watermark": "Confidential",
    "noDownload": true,
    "oneTime": false
  }'

Node.js（Fetch）

const response = await fetch('https://previewfile.dev/api/u', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    url: 'https://example.com/document.pdf',
    ttlMinutes: 120,
    watermark: 'Confidential',
    noDownload: true,
    oneTime: false
  })
});

const data = await response.json();
console.log(data.data.previewUrl);

Python（Requests）

import requests

response = requests.post(
    'https://previewfile.dev/api/u',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'url': 'https://example.com/document.pdf',
        'ttlMinutes': 120,
        'watermark': 'Confidential',
        'noDownload': True,
        'oneTime': False
    }
)

data = response.json()
print(data['data']['previewUrl'])

Java（HttpClient）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String json = """
{
  "url": "https://example.com/document.pdf",
  "ttlMinutes": 120,
  "watermark": "Confidential",
  "noDownload": true,
  "oneTime": false
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://previewfile.dev/api/u"))
    .header("Content-Type", "application/json")
    .header("x-api-key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);

System.out.println(response.body());

C#（HttpClient）

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = new
{
    url = "https://example.com/document.pdf",
    ttlMinutes = 120,
    watermark = "Confidential",
    noDownload = true,
    oneTime = false
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://previewfile.dev/api/u", content);
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

API 概览

On this page