결론부터 말씀드리면: SmartSlim Server는 RESTful API를 제공하며, 업로드 압축, 일괄 압축, 상태 조회, 콜백 알림의 4가지 핵심 인터페이스를 포함하고, API Key와 Bearer Token 두 가지 인증 방식을 지원합니다. 단일 파일 업로드 압축의 경우 100MB PDF가 약 8초 만에 완료되며, 일괄 압축 100개 파일은 약 12초가 소요됩니다. 기본 요청 제한은 분당 60회이며, Enterprise 버전은 300회까지 확장할 수 있습니다. 본문에서는 4가지 인터페이스의 매개변수 상세 표, Python/JavaScript/curl 호출 예제 및 오류 처리 방안을 제시합니다. 아래에서는 API 개요부터 시작하여 각 인터페이스를 하나씩 상세히 설명하겠습니다.
HTTP API 호출이 아닌 SDK 로컬 통합이 필요하시다면, 먼저 압축 SDK 통합 가이드: Python/Java/C# 다국어 호출을 읽어보시기를 권장합니다.
1. API 인터페이스 개요
SmartSlim Server의 RESTful API는 FastAPI 프레임워크를 기반으로 개발되었으며, 모든 인터페이스는 JSON 형식 데이터를 반환하고 multipart/form-data 파일 업로드를 지원합니다. API 기본 경로는 /api/v1/이며, 모든 요청은 반드시 인증 정보를 포함해야 합니다.
| 인터페이스 | 메서드 | 경로 | 기능 | 동기/비동기 |
|---|---|---|---|---|
| 업로드 압축 | POST | /api/v1/compress | 단일 파일 업로드 및 압축 | 동기(50MB 이하)/비동기 |
| 일괄 압축 | POST | /api/v1/compress/batch | 다중 파일 일괄 업로드 압축 | 비동기 |
| 상태 조회 | GET | /api/v1/status/{task_id} | 압축 작업 상태 조회 | 동기 |
| 콜백 알림 | POST | 클라이언트 콜백 URL | 압축 완료 후 능동적 알림 | 비동기 푸시 |
인증 방식은 두 가지로 나뉩니다. API Key 인증은 서버 측 호출에 적합하고, Bearer Token 인증은 프런트엔드 호출에 적합합니다. 아래 표는 두 인증 방식의 특징을 비교합니다.
| 인증 방식 | 요청 헤더 | 유효 기간 | 적용 시나리오 | 보안성 |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | 영구(취소 가능) | 서버 측 호출 | 중간(HTTPS 필요) |
| Bearer Token | Authorization: Bearer token | 24시간 | 프런트엔드 호출 | 높음(단기 유효) |
2. 인터페이스별 매개변수 상세 설명
2.1 업로드 압축 인터페이스
업로드 압축 인터페이스는 단일 파일을 받아 압축 결과를 반환합니다. 50MB 이하 파일은 동기적으로 압축 후 다운로드 링크를 반환하며, 50MB 초과는 비동기적으로 작업 ID를 반환합니다.
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| file | multipart/file | 예 | - | 압축할 파일 |
| format | string | 아니오 | 자동 감지 | 파일 유형(pdf/image/ofd) |
| level | string | 아니오 | medium | 압축 레벨(low/medium/high/ultra) |
| quality | integer | 아니오 | 75 | 품질 계수(1-100) |
| callback_url | string | 아니오 | - | 비동기 콜백 알림 URL |
2.2 일괄 압축 인터페이스
일괄 압축 인터페이스는 다중 파일을 받아 비동기 처리 후 일괄 작업 ID를 반환합니다. 동시성 수를 지정할 수 있으며, 최대 동시성은 라이선스 제한을 받습니다.
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| files | multipart/file[] | 예 | - | 압축할 파일 목록(최대 100개) |
| level | string | 아니오 | medium | 압축 레벨 |
| quality | integer | 아니오 | 75 | 품질 계수 |
| workers | integer | 아니오 | 4 | 동시성 수(1-16) |
| callback_url | string | 아니오 | - | 완료 콜백 URL |
2.3 상태 조회 인터페이스
상태 조회 인터페이스는 작업 ID를 통해 비동기 압축 작업의 현재 상태와 결과를 조회합니다.
| 반환 필드 | 유형 | 설명 |
|---|---|---|
| task_id | string | 작업 고유 식별자 |
| status | string | 상태(pending/processing/completed/failed) |
| progress | integer | 진행률 백분율(0-100) |
| download_url | string | 압축 결과 다운로드 링크(완료 후) |
| original_size | integer | 원본 파일 크기(바이트) |
| compressed_size | integer | 압축 후 크기(바이트) |
| error | string | 오류 정보(실패 시) |
3. 세 가지 언어 호출 예제
아래에서는 curl, Python, JavaScript 세 가지 언어의 호출 예제를 제시하며, 모두 단일 PDF 파일 업로드 압축을 예로 듭니다.
| 언어 | 핵심 코드 | 설명 |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | 명령줄 호출 |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | requests 라이브러리 |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
4. 요청 제한 및 오류 처리
API는 완비된 요청 제한과 오류 처리 메커니즘을 갖추고 있습니다. HTTP 상태 코드와 오류 코드를 이해해야만 견고한 호출 코드를 작성할 수 있습니다.
| HTTP 상태 코드 | 오류 코드 | 의미 | 처리 권장 |
|---|---|---|---|
| 200 | - | 성공 | 응답 데이터 파싱 |
| 400 | INVALID_PARAM | 매개변수 오류 | 요청 매개변수 점검 |
| 401 | UNAUTHORIZED | 인증 실패 | API Key/Token 점검 |
| 413 | FILE_TOO_LARGE | 파일 한도 초과 | 청크 업로드 사용 |
| 429 | RATE_LIMITED | 요청 빈도 초과 | 지수 백오프 재시도 |
| 500 | INTERNAL_ERROR | 서버 오류 | 재시도 또는 지원팀 연락 |
| 503 | SERVICE_UNAVAILABLE | 서비스 이용 불가 | 대기 후 재시도 |
요청 제한 정책 상세: 기본적으로 분당 60회 요청, 초당 10회 동시, Enterprise 버전은 분당 300회, 초당 30회 동시. 한도를 초과하면 429를 반환하며, 응답 헤더에 X-RateLimit-Remaining(잔여 횟수)과 X-RateLimit-Reset(재설정 타임스탬프)을 포함합니다. 클라이언트에서 지수 백오프 재시도 구현을 권장합니다: 429 수신 후 1초 대기 후 재시도, 실패 시 2초, 다시 실패 시 4초 대기, 최대 3회 재시도.
| 파일 유형 | 원본 크기 | 압축 후 크기 | 압축 소요 시간 | 압축률 |
|---|---|---|---|---|
| PDF(스캔본) | 80MB | 8.2MB | 6.5초 | 89.8% |
| PDF(전자 버전) | 15MB | 3.1MB | 1.2초 | 79.3% |
| JPEG 이미지 | 12MB | 2.8MB | 0.8초 | 76.7% |
| PNG 이미지 | 25MB | 6.5MB | 1.5초 | 74.0% |
| OFD 문서 | 30MB | 5.2MB | 2.0초 | 82.7% |
압축 작업 큐의 저수준 설계 원리를 이해하려면 압축 작업 큐 설계를 참조하시기 바랍니다. Docker로 API 서비스를 배포해야 한다면 Docker로 압축 서비스 배포를 참조하시기 바랍니다.
5. 자주 묻는 질문(FAQ)
Q1: 압축 API는 어떻게 인증하여 호출하나요?
SmartSlim Server의 압축 API는 두 가지 인증 방식을 지원합니다. API Key 인증(요청 헤더 X-API-Key에 키 전달, 서버 측 호출에 적합)과 Bearer Token 인증(Authorization 헤더에 JWT Token 전달, 프런트엔드 호출에 적합). API Key는 영구 유효하지만 언제든지 취소할 수 있으며, Token은 24시간 유효하여 정기적으로 새로 고쳐야 합니다. 운영 환경에는 API Key 방식을 권장하며, 간단하고 안정적입니다.
Q2: 압축 API는 어떤 파일 형식을 지원하나요?
SmartSlim 서버 버전 API는 PDF, 이미지(jpg/jpeg/tif), OFD 형식을 지원하며, 단일 파일 한도 1GB입니다. SmartSlim 네트워크 버전 API는 10개 분야 40종 이상의 형식 전체(비디오, 오디오, Office 문서 등 포함)를 지원하며, 단일 파일 한도 10GB입니다. 호출 시 format 매개변수로 파일 유형을 지정하며, 전달하지 않으면 자동 감지됩니다. 서버 버전은 PDF/이미지/OFD 세 가지 형식만 지원하므로, 전체 형식이 필요하면 네트워크 버전이 필요합니다.
Q3: 압축 API에 호출 빈도 제한이 있나요?
서비스 안정성을 보호하기 위한 요청 제한 정책이 있습니다. 기본 제한: 분당 60회 요청, 초당 10회 동시. 한도를 초과하면 429 상태 코드를 반환하며, 응답 헤더에 X-RateLimit-Remaining 및 X-RateLimit-Reset 필드를 포함합니다. Enterprise 버전은 분당 300회, 초당 30회 동시까지 확장할 수 있습니다. 클라이언트에서 지수 백오프 재시도 메커니즘 구현을 권장하며, 429 수신 후 1-2-4초로 점진적 대기 후 재시도합니다.
Q4: 압축 API에서 대용량 파일은 어떻게 처리하나요?
대용량 파일(50MB 초과)은 청크 업로드 인터페이스 사용을 권장하며, 파일을 5MB 청크로 나누어 업로드하고, 모든 업로드 완료 후 병합 및 압축을 알립니다. 압축 완료 후 콜백 알림 또는 상태 조회 인터페이스 폴링을 통해 결과를 가져옵니다. 대용량 파일 압축은 비동기 방식으로 진행되며, API 호출을 차단하지 않습니다. 100MB PDF 압축은 약 8초, 1GB 비디오 압축은 약 90초가 소요되며, 완료 후 자동으로 다운로드 링크가 생성됩니다.
결론
SmartSlim Server의 RESTful API는 업로드 압축, 일괄 압축, 상태 조회, 콜백 알림의 4가지 인터페이스를 제공하여, 단일 파일부터 대량 처리까지의 전 시나리오를 포괄합니다. 인증 방식 이중 선택: API Key는 서버 측, Bearer Token은 프런트엔드에 적합. 요청 제한 정책이 명확합니다: 기본 분당 60회, Enterprise 버전 300회, 429 상태 코드와 지수 백오프 재시도를 함께 사용. 80MB 스캔 PDF를 8.2MB로 압축하는 데 단 6.5초, 압축률 89.8%입니다.
세 가지를 기억하시기 바랍니다. 첫째, 50MB 이하는 동기적으로 결과를 반환하고, 그 초과는 비동기적으로 작업 ID로 조회. 둘째, 429 요청 제한에 대해서는 지수 백오프 재시도를 구현하며, 무작위 재시도를 하지 마십시오. 셋째, 대용량 파일은 청크 업로드 인터페이스를 사용하며, 5MB 청크로 분할 업로드합니다. 적합한 인터페이스와 매개변수를 선택하면, 압축 API 호출은 사실 매우 간단합니다. HTTP 호출보다 로컬 SDK 통합을 선호하신다면, 압축 SDK 통합 가이드를 참조하시기 바랍니다.