2026-07-11 13:52:47 +08:00
|
|
|
---
|
|
|
|
|
description: "AVIF, JXL, HEIC와 같은 최신 형식을 포함하여 이미지를 형식 간에 변환합니다."
|
2026-07-15 21:55:51 +08:00
|
|
|
i18n_source_hash: 2639f333073f
|
2026-07-11 13:52:47 +08:00
|
|
|
i18n_provenance: human
|
|
|
|
|
i18n_output_hash: 4d24e322a7ac
|
|
|
|
|
---
|
|
|
|
|
|
2026-07-15 21:55:51 +08:00
|
|
|
# 이미지 변환 {#convert}
|
2026-07-11 13:52:47 +08:00
|
|
|
|
|
|
|
|
이미지를 형식 간에 변환합니다. 일반적인 웹 형식은 물론 HEIC, JXL, BMP, ICO, JP2, QOI, PSD와 같은 특수 형식도 지원합니다.
|
|
|
|
|
|
|
|
|
|
## API 엔드포인트 {#api-endpoint}
|
|
|
|
|
|
|
|
|
|
`POST /api/v1/tools/image/convert`
|
|
|
|
|
|
|
|
|
|
이미지 파일과 JSON `settings` 필드가 포함된 multipart 폼 데이터를 받습니다.
|
|
|
|
|
|
|
|
|
|
## 매개변수 {#parameters}
|
|
|
|
|
|
|
|
|
|
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
|
|
|
|
|
|-----------|------|----------|---------|-------------|
|
|
|
|
|
| format | string | 예 | - | 목표 형식: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `heic`, `heif`, `jxl`, `bmp`, `ico`, `jp2`, `qoi`, `psd`, `ppm`, `eps`, `tga` |
|
|
|
|
|
| quality | number | 아니요 | - | 출력 품질(1~100). jpg, webp, avif, heic와 같은 손실 형식에 적용됩니다. |
|
|
|
|
|
|
|
|
|
|
## 지원되는 출력 형식 {#supported-output-formats}
|
|
|
|
|
|
|
|
|
|
| 형식 | 유형 | 비고 |
|
|
|
|
|
|--------|------|-------|
|
|
|
|
|
| jpg | 손실 | JPEG, 최고의 호환성 |
|
|
|
|
|
| png | 무손실 | 투명도 지원 |
|
|
|
|
|
| webp | 둘 다 | 최신 웹 형식, 우수한 압축 |
|
|
|
|
|
| avif | 손실 | 차세대 형식, 탁월한 압축 |
|
|
|
|
|
| tiff | 둘 다 | 인쇄/출판 워크플로 |
|
|
|
|
|
| gif | 무손실 | 256색으로 제한 |
|
|
|
|
|
| heic / heif | 손실 | Apple 생태계 형식 |
|
|
|
|
|
| jxl | 둘 다 | JPEG XL, 차세대 형식 |
|
|
|
|
|
| bmp | 무손실 | 비압축 비트맵 |
|
|
|
|
|
| ico | 무손실 | Windows 아이콘 형식 |
|
|
|
|
|
| jp2 | 손실 | JPEG 2000 |
|
|
|
|
|
| qoi | 무손실 | Quite OK Image 형식 |
|
|
|
|
|
| psd | 레이어 | Adobe Photoshop(ImageMagick 필요) |
|
|
|
|
|
| ppm | 무손실 | Portable Pixmap (PPM/PGM/PBM) |
|
|
|
|
|
| eps | 벡터 | Encapsulated PostScript |
|
|
|
|
|
| tga | 무손실 | Targa 이미지 형식 |
|
|
|
|
|
|
|
|
|
|
## 요청 예시 {#example-request}
|
|
|
|
|
|
|
|
|
|
WebP로 변환:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
|
|
|
|
|
-H "Authorization: Bearer si_your-api-key" \
|
|
|
|
|
-F "file=@photo.jpg" \
|
|
|
|
|
-F 'settings={"format": "webp", "quality": 85}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
PNG로 변환(무손실):
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
|
|
|
|
|
-H "Authorization: Bearer si_your-api-key" \
|
|
|
|
|
-F "file=@photo.jpg" \
|
|
|
|
|
-F 'settings={"format": "png"}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 응답 예시 {#example-response}
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
|
|
|
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
|
|
|
|
|
"originalSize": 2450000,
|
|
|
|
|
"processedSize": 680000
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 참고 사항 {#notes}
|
|
|
|
|
|
|
|
|
|
- 출력 파일 이름 확장자는 목표 형식에 맞게 자동으로 업데이트됩니다.
|
|
|
|
|
- SVG 입력은 변환 전에 300 DPI로 래스터화됩니다.
|
|
|
|
|
- PSD 변환에는 서버에 ImageMagick이 설치되어 있어야 합니다.
|
|
|
|
|
- BMP, EPS, ICO, JP2, JXL, PPM, QOI, TGA는 특수 CLI 인코더를 사용하며 Sharp 처리를 우회합니다.
|
|
|
|
|
- HEIC/HEIF 인코딩은 시스템 HEIC 인코더 라이브러리를 사용합니다.
|
|
|
|
|
- 입력 형식은 광범위합니다: JPEG, PNG, WebP, AVIF, TIFF, GIF, HEIC, RAW(CR2, NEF, ARW 등), PSD, SVG, BMP 등.
|
