# 이미지 변환

이미지를 SVG로 벡터화하거나 PNG, PDF, TIFF, PPTX로 내보냅니다. 순서도도 지원합니다.

출처: https://scifig.ai/ko/docs/api/image-conversions

## JSON 본문

`POST /images/conversions`. 필요한 범위: `figures:generate`.

| 필드 | 유형 | 필수 | 기본값 | 규칙 |
| --- | --- | --- | --- | --- |
| image | string | 예 | — | 최대 20 MB의 PNG 또는 JPEG `file_id`, 혹은 순서도의 SVG 결과. `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를 반환하며 이번 작업에는 과금하지 않습니다.
- 작업 시작 전에 벡터화 서비스를 일시적으로 사용할 수 없으면 `Retry-After`가 포함된 `503 SERVICE_UNAVAILABLE`을 반환합니다. 같은 키로 재시도하세요.

## PNG, PDF, TIFF 및 PPTX

- 무료이며 계정별 하루 최대 200회 변환할 수 있습니다. 즉시 완료되며, 응답은 `succeeded` 작업입니다.
- 변환은 입력이 모든 검증을 통과한 뒤에만 Idempotency-Key당 한 번씩 일일 한도에 집계됩니다. 같은 키로 재시도해도 다시 집계되지 않습니다. 한도를 초과하면 `details.reason = DAILY_CONVERSION_LIMIT`와 일일 제한 구간이 초기화될 때까지의 `Retry-After`가 포함된 `429 RATE_LIMITED`를 반환합니다.
- 원본은 PNG 또는 JPEG 이미지, 혹은 순서도의 SVG 결과입니다. WebP는 지원하지 않습니다(`UNSUPPORTED_SOURCE_FORMAT`).
- 인코딩된 결과가 24 MiB를 초과하는 파일은 `400 INVALID_REQUEST`(`OUTPUT_TOO_LARGE`)로 거부됩니다. 더 작은 이미지를 변환하세요.
- `dpi`는 파일에 기록되어 PDF 및 PPTX 페이지의 실제 크기를 결정하며, 픽셀을 다시 샘플링하지 않습니다. 픽셀 수를 늘리려면 먼저 [업스케일](/ko/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`)로 거부합니다. 렌더러 자체에 장애가 있으면 `Retry-After`가 포함된 `503 SERVICE_UNAVAILABLE`(`SVG_RENDERER_UNAVAILABLE`)을 반환하므로 같은 키로 재시도하세요. 다른 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())
```