배치

배치는 함께 처리하고, 상태를 확인하며, 결과를 가져오는 하나 이상의 문서로 구성된 명명된 그룹입니다. 배치를 명시적으로 생성할 필요는 없습니다. 해당 batch_name으로 문서를 처음 업로드할 때 암시적으로 생성됩니다(문서 업로드 참조).

배치 처리 시작

현재 배치에 있는 모든 적격 문서에 대한 추출을 시작합니다. 이 엔드포인트는 실제로 크레딧을 사용하며, 대기열에 추가된 문서당 1크레딧이 차감됩니다.

POST /api/v1/batches/{batch_name}/process

매개변수

이름	위치	유형	설명
`batch_name`	path	string	처리할 배치입니다.
`template_id`	body (JSON)	integer, optional	적용할 저장된 템플릿입니다. `fields`와 함께 제공된 경우 `template_id`가 우선합니다.
`fields`	body (JSON)	array, optional	이번 실행에만 사용할 임시 필드 목록입니다. — `[{"name": "...", "format_requirement": "..."}]` 또는 일반 이름 문자열 배열입니다. `template_id`가 제공되면 무시됩니다. 둘 다 생략하면 모델이 자체적으로 열을 추론합니다.
`quality`	body (JSON)	string, optional	`"fast"` 또는 `"high"`입니다. 생략하면 계정의 `thinking_type` 설정이 사용됩니다. — 계정 설정 및 API 동작을 참조하세요.
`webhook_url`	body (JSON)	string, optional	동일한 호출에서 이 배치의 완료 콜백을 등록합니다. — 배치 Webhook 등록을 호출하는 것과 동일합니다. `http://` 또는 `https://`여야 합니다.
`Idempotency-Key`	header, optional	string	강력히 권장됩니다. 이 엔드포인트는 크레딧을 차감합니다. 멱등성을 참조하세요.

quality는 API가 호출별로 재정의할 수 있게 허용하는 유일한 계정 설정입니다. 다른 모든 계정 수준 기본 설정은 계정에서 읽어오며 요청별로 재정의할 수 없습니다. 전체 내용은 계정 설정 및 API 동작을 참조하세요. 여기에는 auto_annotate_bbox로 인해 해당 엔드포인트를 호출하지 않았더라도 이 호출에 bbox 주석 비용이 청구될 수 있는 이유도 포함됩니다.

응답의 webhook_registered는 이 특정 호출만 반영합니다 — 이 요청에 webhook_url이 포함된 경우에만 true이며, 배치에 webhook이 있는지 여부를 나타내는 것은 아닙니다. 이전에 배치 webhook 등록을 통해 webhook이 설정된 배치는 완료 시 콜백이 올바르게 실행되지만, 이 필드는 해당 호출에 대해 false를 반환합니다. 이미 BatchWebhook이 존재하는지 확인하지 않기 때문입니다. 여기서 false가 반환되었다고 "이 배치에 대해 webhook이 실행되지 않는다"고 판단하지 마십시오.

이미 처리하고 알림을 받은 배치에 추가 문서를 업로드한 후 이 엔드포인트를 다시 호출하면, 배치의 webhook이 이미 실행된 경우 자동으로 재설정되어 새 문서 배치의 완료도 알림을 받게 됩니다. 이를 위해 추가 호출이 필요하지 않습니다. 정확한 의미는 Webhooks 가이드의 "배치 재처리" 섹션을 참조하세요.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
batch_not_found — 계정에서 이 batch_name 아래에 문서가 존재하지 않습니다.
invalid_parameter — 잘못된 quality/webhook_url/template_id 값이거나, 배치에서 현재 처리 가능한 문서가 없습니다.
template_not_found
insufficient_credits — 대기 중인 문서를 처리하기에 충분한 크레딧이 없습니다.

배치 목록 조회

페이지별로 필터링 가능한 배치 요약 목록을 반환합니다. API 사용자를 위한 "Files Filter" 기능입니다. 요약 정보만 반환하며, 특정 배치의 전체 문서별 데이터는 배치 결과 조회를 사용하세요.

GET /api/v1/batches

파라미터

이름	위치	타입	설명
`source`	query, 선택	string	`direct`, `collect`, `email_inbox`, `api`, 또는 `share` 중 하나. 생략 시 모든 소스.
`q`	query, 선택	string	배치 내 파일 이름에 대한 대소문자 구분 없는 부분 문자열 일치.
`date_from`	query, 선택	string (`YYYY-MM-DD`)	업로드 시간의 포함 하한.
`date_to`	query, 선택	string (`YYYY-MM-DD`)	업로드 시간의 포함 상한.
`status`	query, 선택	string	필터링할 공개 상태(`queued,processing,succeeded,failed,canceled`)의 쉼표로 구분된 목록.
`template_id`	query, 선택	integer	이 템플릿을 사용한 배치만.
`mode`	query, 선택	string	현재 허용되는 유일한 값은 `"table"`입니다. 향후 추출 모드를 위해 예약됨.
`limit`	query, 선택	integer	1–100. 기본값 20.
`page_token`	query, 선택	string	이전 응답의 `next_page_token`에서 가져온 불투명 커서. 페이지네이션 참조.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
invalid_parameter — mode, limit, status, 또는 page_token이 잘못되었습니다.

배치 상태 가져오기

하나의 배치에 대한 간단한 집계 상태 — 공개 상태별 개수와 all_done 플래그를 포함합니다. 아직 전체 결과 페이로드가 필요하지 않은 가벼운 폴링 루프에 유용합니다.

GET /api/v1/batches/{batch_name}

매개변수

이름	위치	유형	설명
`batch_name`	path	string	확인할 배치입니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
batch_not_found

배치 결과 가져오기

추출된 데이터를 검색하는 주요 방법입니다. 배치의 모든 문서는 재구성된 line_items와 함께 반환됩니다. line_items는 추출된 각 행당 하나씩, {field_name: value} 객체의 배열입니다. 필드 값은 기본적으로 단순 스칼라입니다.

GET /api/v1/batches/{batch_name}/results

매개변수

이름	위치	유형	설명
`batch_name`	path	string	결과를 가져올 배치입니다.
`include`	query, optional	string	`"bbox"` — 설정되면 모든 필드 값이 단순 스칼라 대신 `{"value": ..., "bbox": {...}\|null}`가 되고, 각 문서에 `bbox_status` 필드가 추가됩니다. 아래 참조 — 이는 새로운 bbox 작업을 절대 트리거하지 않으며, 이미 계산된 결과만 반환합니다.

?include=bbox는 사전 채워진 결과만 읽습니다. 사용자 대신 bbox 주석 트리거를 호출하지 않습니다. 문서에 대해 bbox가 트리거된 적이 없는 경우, 해당 문서의 필드는 단순히 "bbox": null로 반환됩니다.

순수 위치 필드는 세 번째 별도 형태입니다. 일부 템플릿 필드는 텍스트를 추출하는 대신 무언가를 찾도록 모델에 요청합니다. 해당 필드의 경우 전체 값이 위치입니다. 따라서 위의 스칼라나 {"value","bbox"} 쌍 대신 {"type": "image_region", "bbox": {...}, "image_url": "..."}을 받게 됩니다. ?include=bbox 설정 여부와 관계없이 — 여기서 박스는 선택적 메타데이터가 아니라 필드의 유일한 내용입니다. image_url은 바로 가져올 수 있는 잘린 JPEG을 가리킵니다(문서 이미지 가져오기 참조). 따라서 네 개의 숫자로 원본을 직접 자를 필요가 없습니다.

모든 bbox 객체는 "unit": "normalized"를 사용합니다. 좌표는 페이지의 너비/높이를 기준으로 0에서 1 사이의 부동소수점이며, 픽셀이나 0–1000 스케일이 아닙니다. 정확도에 대한 주의사항은 Bounding Boxes 가이드를 참조하세요. 이 좌표들은 픽셀 수준의 검증 과정 없이 모델에서 직접 가져온 것이므로, 복잡하거나 빽빽한 문서에서는 정확하다기보다 "근사치"로 간주해야 합니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — Error Handling을 참조하세요.
batch_not_found

배치 내보내기

편의를 위한 다운로드 기능입니다. 위의 results는 이 API가 구축된 표준적인 구조화된 형식이며, 이 엔드포인트는 재구성 코드를 직접 작성하지 않고도 동일한 데이터를 스프레드시트로 가져오기 위해 존재합니다. xlsx만 지원합니다. v1은 테이블 모드만 지원하며, 메인 앱의 Word(docx) 내보내기는 전적으로 page_word 모드의 기본 출력이며 v1에서는 제공되지 않습니다. 여기에는 "Word 문서 형태의 테이블 데이터" 옵션이 없습니다.

GET /api/v1/batches/{batch_name}/export

매개변수

이름	위치	유형	설명
`batch_name`	path	string	내보낼 배치입니다.
`format`	query, 선택 사항	string	`xlsx`만 허용됩니다.

응답은 JSON이 아닌 파일 다운로드(Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)입니다. 이 엔드포인트에 대한 응답 JSON 예시는 없습니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
batch_not_found
invalid_parameter (param: "format") — xlsx 이외의 값입니다.

배치 삭제

배치 내 모든 문서를 영구 삭제합니다. queued 상태인 문서는 삭제 전에 환불됩니다. 또한 배치의 Webhook 등록과 문서에 연결된 bbox 주석 작업도 함께 제거됩니다.

DELETE /api/v1/batches/{batch_name}

매개변수

이름	위치	유형	설명
`batch_name`	path	string	삭제할 배치입니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
batch_not_found — 다른 리소스와 달리, 소유하지 않거나 존재하지 않는 batch_name을 삭제하려고 하면 자동으로 무시되지 않고 404 오류가 반환됩니다.