🔌 HWP API
한글(.hwp/.hwpx) 문서를 API 호출 한 번으로 변환·추출합니다. rhwp CLI를 감싼 서비스입니다.
베이스 URL: https://color-me.org/hwp-api
⚡ 직접 해보기
실제 API 를 호출합니다. 문서에 적힌 크레딧이 그대로 차감됩니다.
로그인하면 키 발급 없이 여기서 바로 실행해볼 수 있습니다.
🔒 프라이버시 계약
- 업로드한 파일은 처리 중에만 임시 저장되며, 응답 직후 즉시 삭제됩니다 (보존 0, 백업 없음).
- 로그에는 엔드포인트·파일 크기·소요시간만 남깁니다. 파일명·내용은 기록하지 않습니다.
인증
모든 요청에 Authorization: Bearer hk_... 헤더가 필요합니다. 키는 /my/api-keys 에서 발급합니다 (계정당 최대 5개).
엔드포인트
| 엔드포인트 | 파라미터 | 크레딧 |
|---|---|---|
POST /v1/convert | multipart `file` 또는 raw 본문 + `?to=hwpx|hwp|pdf|text|markdown` (선택 `?name=`) | 1 (10페이지 초과 시 2) |
POST /v1/extract | multipart `file` 또는 raw 본문 + `?kind=text|structure|tables|data|fields|search` (kind=search면 `?search=` 필수) | 1 |
POST /v1/render | multipart `file` 또는 raw 본문 + `?to=png|svg` · `?page=N`(0부터, 생략 시 전체) · `?vlm=claude|gpt4v-low|gpt4v-high|gemini|qwen-vl|llava` 또는 `?maxDim=` / `?scale=` (선택 `?profile=screen|print|high-quality|fast-preview`) | 페이지당 1 |
GET /v1/usage | 없음 (Bearer 키만) | 0 |
예시
multipart 업로드
curl -H "Authorization: Bearer hk_..." \
-F "[email protected]" \
"https://color-me.org/hwp-api/v1/convert?to=text"raw 본문 업로드
curl -H "Authorization: Bearer hk_..." \
--data-binary @doc.hwp \
"https://color-me.org/hwp-api/v1/convert?to=text&name=doc.hwp"에러 코드
| 코드 | 의미 | 설명 |
|---|---|---|
| 401 | 인증 실패 | 키가 없거나, 형식이 올바르지 않거나, 폐기된 키입니다. |
| 402 | 크레딧 부족 | 보유 크레딧이 부족합니다. /my/credits 에서 충전하세요. |
| 408 | 처리 시간 초과 | 문서 처리가 60초를 넘겨 중단되었습니다. |
| 413 | 파일 크기 초과 | 업로드 파일이 20MB를 넘습니다. |
| 422 | 처리 불가 | 비밀번호로 보호되었거나 손상된 문서 등 처리할 수 없는 파일입니다. |
| 429 | 요청 한도 초과 | 키당 분당 60회 제한을 넘었습니다. 잠시 후 다시 시도하세요. |
| 503 | 일시적 사용 불가 | 서버가 준비되지 않았거나 대기열이 가득 찼습니다. 잠시 후 재시도하세요. |
모든 에러는 { error, code } JSON으로 반환됩니다. 처리 실패(402 제외) 시 크레딧은 차감되지 않습니다.
🪙 크레딧
API 호출은 Mini Hub 크레딧을 사용합니다(가입 시 지급되는 크레딧으로 바로 체험할 수 있습니다). 잔액과 충전은 /my/credits에서 확인하고, 키별 사용량은 GET /v1/usage로 조회합니다.