문서 파싱
PDF·DOCX·PPTX·HWP·HWPX 문서를 마크다운으로 변환합니다.
문서는 마인드로직이 직접 운영하는 파서에서 처리되며, 파일이 외부 서비스로 나가지 않습니다. 변환은 작업 제출 → 상태 폴링 → 결과 조회의 3단계로 진행됩니다.
참고
대부분의 문서는 수 초 안에 끝납니다. 폴링 간격은 2초를 권장하며, 결과는 완료 후 24시간 동안 보관됩니다.
- 인증은 다른 게이트웨이 엔드포인트와 같습니다 —
Authorization: Bearer <API_KEY>. - 요청은 JSON 이 아니라
multipart/form-data입니다. 파일은 25MB 를 넘을 수 없습니다(초과 시413). - 스캔 페이지(텍스트 레이어가 없는 페이지)는 OCR 하지 않습니다. 결과의
scanned_pages에 페이지 번호로 알려 드리며 과금하지 않습니다. 문서 전체가 스캔본이면no_text_layer로 실패하고 과금되지 않습니다.
엔드포인트
| Method | Path | 설명 |
|---|---|---|
| POST | /v1/gateway/documents/parse/ | 파싱 작업 제출 (202) |
| GET | /v1/gateway/jobs/{job_id}/ | 작업 상태 폴링 |
| GET | /v1/gateway/jobs/{job_id}/result/ | 완료된 작업의 결과 조회 |
| POST | /v1/gateway/jobs/{job_id}/cancel/ | 작업 취소 |
| GET | /v1/gateway/jobs/?limit=20 | 내 작업 목록 (최신순, 최대 100) |
1. 파싱 작업 제출
POST
/v1/gateway/documents/parse/문서를 업로드해 비동기 파싱 작업을 시작합니다. 본문은
multipart/form-data 입니다.파라미터
file
변환할 문서. 확장자로 형식을 판별합니다: file
required
pdf, docx, pptx, hwp, hwpx. 그 밖의 형식은 400.want_images
기본값 boolean
false. true 이면 결과에 문서 안 이미지가 base64 로 함께 담깁니다.응답 (202)
202)2. 상태 폴링
GET
/v1/gateway/jobs/{job_id}/| Status | 의미 |
|---|---|
queued | 제출됨, 아직 시작 전 |
processing | 파싱 중 |
completed | 결과 준비 완료 — credits_charged 확정, expires_at 까지 결과 보관 |
failed | 실패 — error.code 참고, 과금 없음 |
cancelled | 완료 전에 취소됨, 과금 없음 |
expired | 결과 보관 기간(24시간) 경과 |
error.code 값:| 코드 | 의미 |
|---|---|
no_text_layer | 문서 전체에 텍스트 레이어가 없음(스캔본). 스캔 문서는 지원하지 않습니다 |
unreadable_document | 파서가 문서를 읽지 못함(손상·암호화) |
parser_unavailable | 파서 일시 장애. 잠시 후 다시 제출하세요 |
output_too_large | 변환 결과가 8,000,000자를 초과 |
worker_lost | 처리 중 서버가 재시작됨. 다시 제출하세요 |
3. 결과 조회
GET
/v1/gateway/jobs/{job_id}/result/completed 상태에서만 응답합니다(그 외 상태는 409, 보관 기간이 지났으면 404).page_count— 문서의 전체 페이지 수.billed_pages— 텍스트 레이어에서 추출해 과금된 페이지 수 (page_count− 스캔 페이지 수, 최소 1).scanned_pages— 텍스트 레이어가 없어 건너뛴 페이지 번호(1부터). 이 페이지의 내용은 결과에 없습니다.acceptable— 파서의 품질 판정.false여도 결과는 그대로 반환되며 과금됩니다.images—want_images=true일 때만 포함됩니다.
4. 작업 취소
POST
/v1/gateway/jobs/{job_id}/cancel/queued 또는 processing 상태의 작업을 취소합니다. 취소된 작업은 과금되지 않습니다. 이미 완료된 작업은 그대로 반환되며 환불되지 않습니다.5. 작업 목록
GET
/v1/gateway/jobs/API 키 소유자의 작업을 최신순으로 반환합니다.
limit 은 1–100(기본 20). 다른 사용자의 작업 ID 는 404 입니다.전체 흐름 (Python)
과금
텍스트 레이어가 있는 페이지당 ₩1.8 입니다. 작업이 완료될 때 실제 페이지 수로 과금되며, 스캔 페이지·실패·취소는 과금되지 않습니다.
원화 단가는 크레딧으로 환산되어 차감됩니다(현재 1 크레딧 = US$0.001, 페이지당 약 1.33 크레딧). 제출 시점에 페이지 수만큼 크레딧이 예약되며, 잔액이 부족하면
402 로 거절됩니다.조직 설정에서 API Gateway 가 꺼져 있으면
403, 파서를 제공하지 않는 호스트에서는 503 이 반환됩니다.마지막 수정 날짜: Sep 20, 2026