가이드
API의 각 설계 결정은 참조 문서에 한 줄로만 적히지 않고, 여기에서 별도 페이지로 다룹니다. 비동기 작업 모델, 웹훅, 멱등성, 페이지 매김, 오류 처리, 속도 제한, bbox, 그리고 계정 수준 설정이 API 호출과 상호작용하는 방식까지 포함합니다.
비동기 작업 모델
v1 API에서 문서 및 배치 처리가 비동기로 작동하는 방식 — 대기 중/처리 중/성공/실패/취소 상태 머신과 created_at/started_at/completed_at 타임스탬프 체인.
웹훅
폴링 대신 배치 완료 시 알림을 받을 콜백 URL을 등록하세요. Standard Webhooks 서명 검증, 이벤트 페이로드 구조, 재시도 동작, bbox 완료 이벤트, 그리고 배치 재처리 시 자동으로 다시 알림을 받는 방법을 다룹니다.
멱등성
Idempotency-Key 헤더를 사용하여 문서 업로드, 배치 처리, bbox 트리거를 안전하게 재시도하세요. 동일한 작업이 두 번 실행되거나 비용이 이중으로 청구되지 않습니다.
페이지네이션
v1 API의 목록 엔드포인트는 페이지 번호 대신 불투명한 커서 기반 페이지네이션을 사용합니다. next_page_token을 그대로 전달하며, 직접 디코딩하거나 생성하지 않습니다.
오류 처리
모든 v1 오류는 type, code, message, doc_url을 포함하는 JSON 객체입니다. 이 페이지는 전체 오류 유형 분류와 모든 개별 오류 코드를 문서화하며, 반환된 doc_url이 연결되는 대상입니다.
속도 제한
v1 속도 제한은 IP 주소가 아닌 계정별로 적용되며, 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더가 포함되어 429 오류가 발생하기 전에 자체적으로 조절할 수 있습니다.
경계 상자(bbox)
bbox는 선택 사항이며 별도로 청구되는 두 번째 패스로, 각 추출 값이 페이지의 어디에서 왔는지 정확히 찾아냅니다. 모델이 직접 제공하는 좌표이며 픽셀 수준의 검증은 없으므로 정밀도는 근사치로 간주하세요.
계정 설정 및 API 동작
v1은 별도의 API 구성 계층을 노출하지 않고 계정의 웹 앱 설정을 직접 읽습니다. 이 페이지에서는 API가 항상 따르는 설정과 요청별로 재정의할 수 있는 설정을 정확히 설명합니다.