# 圖片轉換

將圖片向量化為 SVG，或匯出 PNG、PDF、TIFF 和 PPTX，也支援流程圖。

來源：https://scifig.ai/zh-Hant/docs/api/image-conversions

## JSON 請求體

`POST /images/conversions`。所需權限範圍：`figures:generate`。

| 欄位 | 類型 | 必填 | 預設值 | 規則 |
| --- | --- | --- | --- | --- |
| image | string | 是 | — | PNG 或 JPEG 的 `file_id`，或流程圖的 SVG 輸出，最大 20 MB；`svg` 也接受 WebP |
| format | string | 是 | — | `svg`、`png`、`pdf`、`tiff` 或 `pptx` |
| vector_mode | string | 否 | `editable_text` | 僅適用於 `svg`：`editable_text` 或 `full_vector` |
| dpi | integer | 否 | 300 | 不適用於 `svg`：300、600 或 1000 |
| width | integer | 否 | 2048 | 僅適用於流程圖 SVG 原始檔：長邊畫素為 256–4096，總畫素最多 4,194,304 |

## SVG 向量化

- 消耗 150 點數，需要付費方案；使用與網站“在畫布中編輯”相同的向量化工具。原始檔為 PNG、JPEG 或 WebP 圖片。
- `editable_text` 將文字保留為可編輯的 SVG 文字；`full_vector` 將所有內容（包括文字）描摹為路徑。
- 轉換以任務形式執行。向量化任務被接納後才預留點數，任務的 `credits` 從賬本讀回。向量化失敗時返還點數，該金鑰回傳 `TASK_FAILED`。
- 轉換已向量化的圖片時，回傳此前的 SVG，本次任務不扣點數。
- 任務開始前，若向量化服務暫時不可用，則回傳 `503 SERVICE_UNAVAILABLE` 和 `Retry-After`：請用相同金鑰重試。

## PNG、PDF、TIFF 和 PPTX

- 免費，每個帳戶每天最多 200 次轉換。轉換立即完成，響應為 `succeeded` 任務。
- 僅當輸入透過所有校驗後，轉換才計入每日額度；每個 Idempotency-Key 僅計一次，相同金鑰重試不會重複計數。超出額度時，回傳 `429 RATE_LIMITED` 和 `details.reason = DAILY_CONVERSION_LIMIT`，`Retry-After` 指示每日視窗重置前的等待時間。
- 原始檔為 PNG、JPEG 圖片或流程圖 SVG 輸出；不接受 WebP（`UNSUPPORTED_SOURCE_FORMAT`）。
- 編碼後的輸出超過 24 MiB 時，回傳 `400 INVALID_REQUEST`（`OUTPUT_TOO_LARGE`）；請轉換更小的圖片。
- `dpi` 寫入檔案，並決定 PDF 和 PPTX 的實際頁面尺寸，不會重新取樣畫素。需要更多畫素時，請先[放大圖片](/zh-Hant/docs/api/image-upscales)。
- PNG 和 TIFF 需要 PNG 原始檔；PDF 和 PPTX 也接受 JPEG。TIFF 使用無損 Deflate 壓縮。
- PPTX 為包含圖片的單頁幻燈片，不是可編輯形狀。

## 流程圖匯出

流程圖 SVG 輸出可轉換為 PNG、PDF、TIFF 或 PPTX。伺服器使用 Arial 和 Noto 字型渲染，長邊為 `width` 畫素（預設 2048，最多 4096，總畫素最多 4,194,304：正方形圖最多 2048 px）。超過限制時回傳 `400 INVALID_REQUEST`（`RENDER_TOO_LARGE`）。字型無法繪製的文字會回傳 `400 INVALID_REQUEST`（`SVG_NOT_RENDERABLE`），不會顯示為空方框。渲染器本身失敗時，回傳 `503 SERVICE_UNAVAILABLE`（`SVG_RENDERER_UNAVAILABLE`）和 `Retry-After`：請用相同金鑰重試。其他 SVG 檔案不能作為輸入。

## cURL

```bash
curl -X POST https://scifig.ai/api/v1/images/conversions \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<file_id>",
    "format": "pdf",
    "dpi": 600
  }'
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/images/conversions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    Prefer: 'wait=25',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "image": "<file_id>",
    "format": "pdf",
    "dpi": 600
  }),
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os
import uuid

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
    "Prefer": "wait=25",
}
response = requests.post(
    "https://scifig.ai/api/v1/images/conversions",
    headers=headers,
    json={
        "image": "<file_id>",
        "format": "pdf",
        "dpi": 600
    },
    timeout=60,
)
print(response.status_code, response.json())
```