한글 문서 추출
HWP · HWPX 문서를 구조 그대로 JSON 과 Markdown 으로
공개 예정 API 입니다. 아래 내용은 출시 전에 바뀔 수 있습니다.
지원 문서
HWP 5.x · HWPX. 암호가 걸렸거나 배포용으로 저장한 문서는 처리하지 않습니다.
동기 호출
파일을 올리거나 공개 URL 을 넘깁니다. 둘 중 하나만 보냅니다.
curl https://api.code-x.kr/v1/extract \
-H "Authorization: Bearer $CODEX_API_KEY" \
-F file=@공고문.hwp \
-F format=markdown 옵션
| 이름 | 값 | 기본 | 설명 |
|---|---|---|---|
format | json · markdown | json | 블록 트리 JSON 또는 Markdown |
structure | inferred · raw | inferred | 항목 기호로 제목 구조를 되살릴지 |
styles | none · basic | none | 굵게 · 기울임 · 밑줄 · 정렬 · 링크 포함 여부 |
images | inline · none | inline | 이미지를 base64 로 담을지 |
응답
{ "mode": true, "code": 200, "message": null,
"data": {
"schemaVersion": 1,
"source": { "format": "HWP5" },
"metadata": { "title": "…", "author": "…" },
"blocks": [
{ "type": "heading", "level": 1, "text": "Ⅰ. 사업 개요" },
{ "type": "paragraph", "text": "…" },
{ "type": "table", "rows": 3, "cols": 4, "cells": [ … ] }
],
"images": { "img1": { "mime": "image/png", "data": "…" } },
"warnings": []
} } 비동기 호출 · 웹훅
큰 문서는 POST /v1/jobs 로 맡기고 결과를 웹훅으로 받습니다. 웹훅 주소는 API 별 설정에서 등록합니다(준비 중).
결과는 우리 서버에 남기지 않으므로 웹훅으로만 전달됩니다.
POST /v1/jobs → 202 { "jobId": "job_…" }
웹훅 job.succeeded · job.failed
헤더 Codex-Signature: t=…,v1=… (웹훅 시크릿으로 HMAC-SHA256 서명) 이 API 의 오류
| HTTP | code | data.error | 뜻 |
|---|---|---|---|
| 400 | 40001 | URL_NOT_ALLOWED | 사설 IP · 허용하지 않는 스킴 · 리다이렉트 초과 |
| 413 | 41301 | FILE_TOO_LARGE | 플랜의 파일 크기 상한 초과 |
| 415 | 41501 | UNSUPPORTED_FORMAT | 한글 문서가 아님 |
| 422 | 42201 | DOCUMENT_ENCRYPTED | 암호 · 배포용 문서 |
| 422 | 42202 | DOCUMENT_CORRUPTED | 문서를 읽을 수 없음 |
| 424 | 42401 | URL_FETCH_FAILED | URL 에서 내려받기 실패 |
| 504 | 50401 | PROCESSING_TIMEOUT | 처리 시간 상한 초과 |
크레딧
문서 1건을 처리할 때마다 파일 크기에 따라 크레딧이 차감됩니다. 추출에 실패한 요청은 차감하지 않고, 테스트 키 호출은 크레딧을 쓰지 않습니다.
| 조건 | 차감 |
|---|---|
| 5MB 이하 | 2 크레딧 |
| 5MB 초과 (플랜의 파일 상한까지) | 5 크레딧 |
| 웹훅(비동기)으로 받기 | +1 크레딧 |
예: 3MB 문서를 웹훅으로 받으면 2 + 1 = 3 크레딧. 차감량은 운영 중 바뀔 수 있으며 이 표는 언제나 현재 값입니다. 요금 · 크레딧 가이드
MCP
AI 에이전트에서는 원격 MCP 서버를 연결해 extract_hwp 도구로 공개 URL 의 문서를 바로 읽을 수 있습니다. 인증은 같은 API 키를 씁니다.