개발자를 위해HTTP API
이 웹사이트는 평범한 HTTP API의 클라이언트예요 ―― 드롭 존이 하는 모든 일을 curl로 할 수 있어요. API는 베타 기간 무료, 키 불필요예요. 속도 제한: IP별 분당 쓰기 요청 30회, 더해 하루 무료 한도(변환 20회 / 음성 3회 / 검사 30회 ―― 실패는 돌려받아요). AI 에이전트: /skill.md를 가리키세요 ―― 이 페이지 전체가 에이전트 친화적 형태로 담겨 있어요.
인증 방식과 한도
API는 키 없이 열려 있어요. 익명 호출자는 무료 IP별 티어(L1)를 공유해요. 더 여유가 필요한 에이전트와 스크립트는 API 키(L2b)를 쓸 수 있어요 ―― 계정 페이지에서 발급하고 Bearer 토큰으로 보내세요. 키마다 자체 하루 한도가 있어요. 키는 SHA-256 해시로 저장되고, 평문은 생성 시 한 번만 보여주며 로그에는 절대 나오지 않아요.
| 신분 | 변환 횟수/일 | 음성/일 | 파일 검사/일 |
|---|
| 익명(IP별) ―― L1 | 20 | 3 | 30 |
| API 키(키별) ―― L2b | 500 | 20 | 300 |
한도는 UTC 자정에 초기화되고, 실패한 변환은 자동으로 돌려받아요. 쓰기는 IP별 분당 30회로 제한돼요.
# 익명(L1) ―― 키 불필요
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"
# API 키 사용(L2b) ―― sk-…를 내 키로 교체
curl -X POST https://liteconvert.cc/api/public/convert \
-H "Authorization: Bearer sk-…" \
-F 'meta={"conversion":"pdf-docx"};type=application/json' \
-F "file=@document.pdf"
401 INVALID_API_KEY: 키가 Bearer 토큰으로 제시됐지만 검증에 실패했어요(무효 또는 철회) ―― 제시된 키는 항상 거부되고 익명으로 강등되지 않아요. 키 없이, 또는 Bearer 키가 아닌 Authorization 헤더와 함께 보낸 요청은 그냥 익명 L1 한도에 포함돼요. 429 QUOTA_EXCEEDED: 이 신분의 하루 한도를 다 썼어요. error.reset_at에 정확한 초기화 시각(UTC 자정)이 담겨 있어요.
더 여유가 필요하세요 ―― 계정 페이지에서 API 키 발급.
엔드포인트
| 메서드 | 경로 | 하는 일 |
|---|
| POST | /api/public/detect | 파일 식별(multipart 파일 필드). 동기식, 20초 이내. |
| POST | /api/public/convert | 변환 제출(multipart meta + 파일). request_id를 반환해요. |
| GET | /api/public/requests/{id} | 요청의 상태, 진행 상황, 산출물. |
| GET | /api/public/requests/recent?limit=20 | 이 기기의 최근 변환(X-Owner-Token 헤더, 익명). |
| GET | /api/public/requests/{id}/artifacts/{name} | 프리사인 다운로드 URL로 302 리다이렉트. |
| GET | /api/public/requests/{id}/timeline | 변환의 사람이 읽을 수 있는 이벤트 트레일. |
| GET | /api/public/stats | 실시간 성공률 통계. |
| GET | /api/public/conversions | 변환 카탈로그(지원하는 모든 쌍). |
| GET | /api/public/catalog | 사이트 빌더용 빌드 매니페스트(family/lossy/steps가 포함된 canonical 키). |
파일 감지
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"
{
"request_id": "c0af…",
"status": "succeeded",
"report": { "declared": "pdf", "detected": "pdf", "match": true,
"mime": "application/pdf", "confidence": 0.99 }
}
변환하고 다운로드
# 1. 제출(URL 소스는 source_url을 담은 meta를 보내고 파일 파트는 없음)
curl -X POST https://liteconvert.cc/api/public/convert \
-F 'meta={"conversion":"pdf-docx"};type=application/json' \
-F "file=@document.pdf"
# → 202 { "request_id": "…", "status": "running" }
# 2. 폴링
curl https://liteconvert.cc/api/public/requests/REQUEST_ID
# → { "status": "succeeded", "artifacts": [{ "name": "docx", "download": "…", … }] }
# 3. 다운로드(프리사인 URL로 302, 1시간 유효)
curl -L -o result.docx https://liteconvert.cc/api/public/requests/REQUEST_ID/artifacts/docx
오류 코드
| 상태 | 코드 | 의미 |
|---|
| 401 | INVALID_API_KEY | 무효한 키가 제시되었거나 키가 철회됐어요. 철회는 즉시 효력이 있어요 ―― 계정 페이지에서 새 키를 발급하세요. |
| 429 | QUOTA_EXCEEDED | 하루 무료 한도 소진(UTC 자정에 초기화, error.reset_at에 정확한 시각). 실패한 변환은 자동으로 돌려받아요. |
| 422 | UNSUPPORTED_CONVERSION | 이 변환 쌍은 카탈로그에 없어요. |
| 404 | ARTIFACT_EXPIRED | 결과가 만료되어 삭제됐어요(24시간 보관) ―― 다시 변환하세요. |
| 413/422 | INTAKE_FAILED | 업로드 실패 또는 200 MB 초과. |
| 502 | CONVERT_FAILED | 엔진들이 시도했지만 이 파일을 읽지 못했어요. 상세 코드(NEEDS_OCR, ENCRYPTED_DOCUMENT, MALFORMED_DOCUMENT)는 고정 메시지와 함께 요청의 error.code로 반환돼요. |
| 400 | INVALID_SOURCE_URL | source_url이 없거나 유효한 공개 http(s) URL이 아니에요. |
| 400 | SOURCE_URL_BLOCKED | 소스 URL이 비공개, 루프백 또는 링크 로컬 주소로 확인되어 차단됐어요(SSRF 보호). |
| 502 | SOURCE_URL_FETCH_FAILED | 소스 URL을 다운로드할 수 없었어요 ―― 오프라인, 시간 초과, 너무 큼, 또는 공개적으로 접근 불가. |
| 503 | CONVERT_API_UNAVAILABLE | 일시적 장애 ―― 1분 후 재시도. |
AI 에이전트를 위해
/skill.md를 가져오세요 ―― 위 엔드포인트, 실전 예제, 무료 티어 선언이 담긴 자족적인 지침서예요. 확실하지 않으면 다시 읽으세요. API와 함께 업데이트돼요.
