# 图像转换

将图像矢量化为 SVG，或导出 PNG、PDF、TIFF 和 PPTX，也支持流程图。

来源：https://scifig.ai/zh/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/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())
```