로컬 API

로컬 API는 여러분의 기기에서 JPGBoost를 HTTP/JSON 서비스로 제공합니다. HTTP 요청을 보낼 수 있는 어떤 언어에서든 가져오기, 설정, 내보내기를 제어할 수 있습니다.

API 활성화하기

API는 기본적으로 비활성화되어 있습니다. 몇 초 만에 활성화할 수 있습니다:

1. 설정(⌘,)을 열고 로컬 API 탭을 선택합니다.
2. 활성화 체크박스를 선택합니다. 서버가 즉시 시작됩니다.
3. 필요하다면 포트를 조정합니다. 기본값은 51823입니다.
4. 바로 아래에 표시되는 인증 토큰을 복사합니다. 버튼을 누르면 언제든지 다시 생성할 수 있습니다.

인증

모든 요청에는 토큰이 담긴 Authorization 헤더가 필요합니다. 이것이 없거나 토큰이 유효하지 않으면 API는 401을 반환합니다.

TOKEN="<설정에 표시된 토큰>"
BASE="http://127.0.0.1:51823/v1"

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

라우트 참조

모든 라우트에는 /v1 접두사가 붙으며, 각 파일의 전후 크기, 압축률, 발생 가능한 오류를 포함한 구조화된 JSON을 반환합니다.

단계별 예시

현재 상태 확인하기

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

파일 가져오기

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/path/to/image1.png", "/path/to/image2.jpg"]}' \
  "$BASE/import"

화질과 포맷 변경하기

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 80, "format": "webp"}' \
  "$BASE/settings"

현재 이미지 목록 보기

응답에는 각 이미지의 식별자, 상태, 전후 크기, 비율, 발생 가능한 오류가 포함됩니다.

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/images"

그룹 내보내기

내보내기는 파일을 쓰기 전에 진행 중인 압축이 끝날 때까지 기다립니다. 이 대기 시간은 waitTimeoutSeconds로 설정할 수 있으며 기본값은 30초입니다.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder": "/path/to/output", "waitTimeoutSeconds": 30}' \
  "$BASE/export"

목록 비우기

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/clear"

특정 이미지에 대한 작업

각 이미지에는 /v1/images에서 반환되는 식별자가 있습니다. 이를 통해 개별적으로 작업할 수 있습니다.

# 이미지 개별 화질 설정
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# 이 이미지를 전체 설정으로 되돌리기
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# 이미지 한 장을 특정 경로로 내보내기
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/output/photo.webp"}' \
  "$BASE/images/<id>/export"

# 그룹에서 이미지 제거
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

API를 통한 내보내기 프로필

API는 인터페이스와 동일한 프로필 목록을 제공합니다. 우선순위 규칙에 대해서는 내보내기 프로필 가이드를 참고하세요. JPGBoost Free에서는 프로필 1개 제한이 여기에도 적용됩니다. POST /v1/profiles는 두 번째 프로필 생성을 거부하지만, 같은 이름으로 기존 프로필을 덮어쓰는 것은 계속 허용합니다.

# 프로필 생성 또는 대체(동일한 이름 = 대체)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/path/to/output"}' \
  "$BASE/profiles"

# 프로필 목록 보기
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# 프로필 삭제하기(공백은 URL에서 %20이 됨)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# 전체 설정에 프로필 적용하기
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# "folder"를 다시 지정하지 않고 프로필의 폴더로 내보내기
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

정상 작동 확인하기

Contents/Resources 안, 앱 내부에 두 개의 스크립트가 포함되어 있습니다. JPGBoost를 열고 API를 활성화한 상태에서 실행하세요. TOKEN 환경 변수가 이미 설정되어 있지 않다면 키보드로 토큰 입력을 요청하며, 설정되어 있다면 지속적 통합에서 연결해 실행할 수도 있습니다.

확인 세트

인증, 라우팅, 매개변수 검증을 ✓/✗ 출력으로 확인합니다. 기본적으로 읽기 전용이며, 이미지를 전달하면 실제 가져오기·내보내기 주기도 함께 수행합니다.

SCRIPTS=/Applications/JPGBoost.app/Contents/Resources

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /path/to/image.png

가이드 투어

토큰 없이 거부되는 상황부터 최종 내보내기까지, 상태, 가져오기, 설정, 목록을 거쳐 위에서 설명한 전체 흐름을 읽기 쉬운 형태로 단계별로 보여줍니다.

"$SCRIPTS/local_api_demo.sh" /path/to/image.png

보안 및 프라이버시

• 서버는 루프백 인터페이스(127.0.0.1)에서만 대기하며, 이는 여러분의 Mac에서만 접근할 수 있다는 뜻입니다. 절대 인터넷에 노출되지 않습니다.
• 어떤 이미지도 인터넷을 거치지 않습니다. API는 로컬 압축 엔진만 제어합니다.
• 토큰은 여러분의 기기에서 생성됩니다. 공유 스크립트에 붙여넣는 등 토큰이 유출되었을 수 있다고 생각되면 다시 생성하세요.
• 사용하지 않을 때는 API를 비활성화하세요. 이것이 기본 상태입니다.