문서 처리

한글 문서 추출

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

옵션

이름값기본설명
formatjson · markdownjson블록 트리 JSON 또는 Markdown
structureinferred · rawinferred항목 기호로 제목 구조를 되살릴지
stylesnone · basicnone굵게 · 기울임 · 밑줄 · 정렬 · 링크 포함 여부
imagesinline · noneinline이미지를 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 의 오류

HTTPcodedata.error뜻
40040001URL_NOT_ALLOWED사설 IP · 허용하지 않는 스킴 · 리다이렉트 초과
41341301FILE_TOO_LARGE플랜의 파일 크기 상한 초과
41541501UNSUPPORTED_FORMAT한글 문서가 아님
42242201DOCUMENT_ENCRYPTED암호 · 배포용 문서
42242202DOCUMENT_CORRUPTED문서를 읽을 수 없음
42442401URL_FETCH_FAILEDURL 에서 내려받기 실패
50450401PROCESSING_TIMEOUT처리 시간 상한 초과

크레딧

문서 1건을 처리할 때마다 파일 크기에 따라 크레딧이 차감됩니다. 추출에 실패한 요청은 차감하지 않고, 테스트 키 호출은 크레딧을 쓰지 않습니다.

조건차감
5MB 이하2 크레딧
5MB 초과 (플랜의 파일 상한까지)5 크레딧
웹훅(비동기)으로 받기+1 크레딧

예: 3MB 문서를 웹훅으로 받으면 2 + 1 = 3 크레딧. 차감량은 운영 중 바뀔 수 있으며 이 표는 언제나 현재 값입니다. 요금 · 크레딧 가이드

MCP

AI 에이전트에서는 원격 MCP 서버를 연결해 extract_hwp 도구로 공개 URL 의 문서를 바로 읽을 수 있습니다. 인증은 같은 API 키를 씁니다.