mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
134 lines
3.9 KiB
Markdown
134 lines
3.9 KiB
Markdown
---
|
||
description: "將 PDF 頁面轉換為高品質影像。"
|
||
i18n_source_hash: 1c36be5dadb8
|
||
i18n_provenance: human
|
||
i18n_output_hash: c32e4df74c3a
|
||
---
|
||
|
||
# PDF 轉影像 {#pdf-to-image}
|
||
|
||
將 PDF 頁面轉換為高品質的點陣影像。支援頁面選擇、多種輸出格式、DPI 控制與色彩模式。包含 info 與 preview 子路由，可在轉換前檢視 PDF。
|
||
|
||
## API 端點 {#api-endpoint}
|
||
|
||
`POST /api/v1/tools/pdf/pdf-to-image`
|
||
|
||
## 參數 {#parameters}
|
||
|
||
| 參數 | 類型 | 必填 | 預設值 | 說明 |
|
||
|-----------|------|----------|---------|-------------|
|
||
| format | string | 否 | `"png"` | 輸出格式：`png`、`jpg`、`webp`、`avif`、`tiff`、`gif`、`heic`、`heif`、`jxl` |
|
||
| dpi | number | 否 | 150 | 渲染解析度（36 至 2400）。DPI 越高產生的影像越大、越精細。 |
|
||
| quality | number | 否 | 85 | 有損格式的輸出品質（1 至 100） |
|
||
| colorMode | string | 否 | `"color"` | 色彩模式：`color`、`grayscale`、`bw`（黑白閾值） |
|
||
| pages | string | 否 | `"all"` | 頁面選擇：`all`、單頁（`3`）、範圍（`1-5`）或以逗號分隔（`1,3,5-8`） |
|
||
|
||
## 範例請求 {#example-request}
|
||
|
||
```bash
|
||
curl -X POST http://localhost:1349/api/v1/tools/pdf/pdf-to-image \
|
||
-F "file=@document.pdf" \
|
||
-F 'settings={"format":"png","dpi":300,"pages":"1-3","colorMode":"color"}'
|
||
```
|
||
|
||
## 範例回應 {#example-response}
|
||
|
||
```json
|
||
{
|
||
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
||
"pageCount": 10,
|
||
"selectedPages": [1, 2, 3],
|
||
"format": "png",
|
||
"pages": [
|
||
{
|
||
"page": 1,
|
||
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/page-1.png",
|
||
"size": 234567
|
||
},
|
||
{
|
||
"page": 2,
|
||
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/page-2.png",
|
||
"size": 198765
|
||
},
|
||
{
|
||
"page": 3,
|
||
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/page-3.png",
|
||
"size": 210456
|
||
}
|
||
],
|
||
"zipUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/pdf-pages.zip",
|
||
"zipSize": 612345
|
||
}
|
||
```
|
||
|
||
## Info 子路由 {#info-sub-route}
|
||
|
||
`POST /api/v1/tools/pdf/pdf-to-image/info`
|
||
|
||
回傳 PDF 的頁數，而不渲染任何頁面。
|
||
|
||
### Info 請求 {#info-request}
|
||
|
||
```bash
|
||
curl -X POST http://localhost:1349/api/v1/tools/pdf/pdf-to-image/info \
|
||
-F "file=@document.pdf"
|
||
```
|
||
|
||
### Info 回應 {#info-response}
|
||
|
||
```json
|
||
{
|
||
"pageCount": 10
|
||
}
|
||
```
|
||
|
||
## Preview 子路由 {#preview-sub-route}
|
||
|
||
`POST /api/v1/tools/pdf/pdf-to-image/preview`
|
||
|
||
以 base64 資料 URL 的形式回傳所有頁面的低解析度 JPEG 縮圖。適用於建立頁面選擇 UI。
|
||
|
||
### Preview 請求 {#preview-request}
|
||
|
||
```bash
|
||
curl -X POST http://localhost:1349/api/v1/tools/pdf/pdf-to-image/preview \
|
||
-F "file=@document.pdf"
|
||
```
|
||
|
||
### Preview 回應 {#preview-response}
|
||
|
||
```json
|
||
{
|
||
"pageCount": 10,
|
||
"thumbnails": [
|
||
{
|
||
"page": 1,
|
||
"dataUrl": "data:image/jpeg;base64,/9j/4AAQ...",
|
||
"width": 300,
|
||
"height": 424
|
||
},
|
||
{
|
||
"page": 2,
|
||
"dataUrl": "data:image/jpeg;base64,/9j/4AAQ...",
|
||
"width": 300,
|
||
"height": 424
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 注意事項 {#notes}
|
||
|
||
- 使用 MuPDF 進行 PDF 渲染，提供高保真的輸出，具備正確的字型渲染與向量圖形。
|
||
- 不支援受密碼保護的 PDF，會回傳 400 錯誤。
|
||
- `pages` 參數支援靈活的語法：
|
||
- `"all"` 或 `""` - 所有頁面
|
||
- `"3"` - 單頁
|
||
- `"1-5"` - 頁面範圍（含端點）
|
||
- `"1,3,5-8"` - 混合個別頁面與範圍
|
||
- 頁碼以 1 為起始。指定超過文件長度的頁面會回傳 400 錯誤。
|
||
- 主端點一律會同時產生個別頁面下載檔以及包含所有選定頁面的 ZIP。
|
||
- Preview 端點以 72 DPI 渲染並縮放至 300px 寬，以快速產生縮圖。縮圖為 60% 品質的 JPEG。
|
||
- Preview 端點會遵循 `MAX_PDF_PAGES` 伺服器設定，限制產生的縮圖數量。
|
||
- 對於高 DPI 的大型文件，處理時間會成比例增加。網頁使用建議採用較低的 DPI（150），列印則採用較高的 DPI（300-600）。
|