시작하기

요청과 응답

모든 도구가 같은 규약을 씁니다.

본문 형식

multipart/form-data 와 application/json 둘 다 받습니다. 파일을 그대로 올릴 때는 multipart 를, 스크립트에서 다룰 때는 JSON(base64)을 쓰면 편합니다.

filesfile[]필수

처리할 파일입니다. 필드 이름은 무엇이든 괜찮고, 올린 순서가 결과 순서가 됩니다.

textstring

글자를 받는 도구(글자 수 세기 · 한영타 · QR)에서만 본문입니다. 파일 도구에서는 같은 이름의 옵션으로 읽힙니다.

(옵션 키)string | number | boolean

도구마다 다릅니다. 각 도구 문서의 옵션 표를 참고하세요. 범위를 벗어난 숫자는 한도로 잘립니다.

응답

okboolean

처리 성공 여부입니다.

toolstring

호출한 도구 id 입니다.

filesobject[]

만들어진 파일입니다. name · size · url 을 담고, 결과가 두 개 이상이면 zip 하나로 묶여 나옵니다.

dataobject

파일이 아닌 결과입니다(글자 수 · 체크섬 등).

notestring

쪽 수·줄어든 용량처럼 결과를 한 줄로 요약한 값입니다.

expiresAtstring (ISO 8601)

이 시각이 지나면 결과가 지워집니다.

결과 내려받기

GET/api/v1/files/{token}/{name}

응답의 files[].url 을 그대로 호출하세요. 토큰을 아는 쪽만 받을 수 있고, 결과 목록을 조회하는 API 는 없습니다. 보관 시간이 지나면 410 을 반환합니다.

도구 명세 읽기

GET/api/v1/tools

GET/api/v1/tools/{id}

입력 조건과 옵션을 코드로 읽을 수 있습니다. OpenAPI 3.1 문서는 /api/openapi.json 에 있습니다.

한도

파일 크기200MB

파일 하나 기준입니다.

파일 개수도구마다

각 도구의 input.min · input.max 를 따릅니다.

처리 시간300초

넘으면 504 를 반환합니다.

보관30분

업로드와 결과 모두 해당합니다.

서버에 변환 엔진이 없어 쓸 수 없는 도구는 ready: false 이고, 호출하면 503 을 반환합니다. 어떤 도구가 그런지는 /api/health 에서 확인할 수 있습니다.

multipart/form-data

curl -X POST https://utils.pah.kr/api/v1/tools/image-resize \
  -F "files=@photo.jpg" \
  -F "width=1280" \
  -F "fit=inside"

application/json

{
  "files": [
    {
      "name": "photo.jpg",
      "content": "/9j/4AAQSkZJRg...",
      "encoding": "base64"
    }
  ],
  "options": { "width": 1280, "fit": "inside" }
}

도구 명세 읽기

{
  "id": "image-resize",
  "name": "이미지 크기 변경",
  "input": {
    "kind": "files",
    "min": 1,
    "max": 50,
    "accept": ["jpg", "png", "webp", "…"]
  },
  "options": [
    { "key": "width", "type": "number", "default": 1920 }
  ],
  "ready": true
}