API 概述

快速開始

PreviewFile.dev 提供簡單的 REST API 從 URL 生成預覽連結。只需一次 API 呼叫即可創建安全、時間限制的預覽連結。

支援 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 金鑰：

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}
取得檔案存取 URL（直鏈或 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'])

功能

110+ 檔案格式：PDF、Office 文件、圖片、影片、程式碼等的原生瀏覽器預覽（查看完整清單）
短連結：使用 nanoid 自動生成的 8 字元識別碼以確保安全性
時間限制：設定 5 分鐘到 24 小時的過期時間
浮水印：為預覽添加自訂文字疊加層
下載控制：選擇性停用檔案下載
一次性連結：首次存取後讓連結過期
隱藏原始 URL：收件人永遠看不到原始檔案 URL
客戶端渲染：所有預覽引擎在瀏覽器中運行以提供最大安全性

API 概述

On this page