참조

Batches

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

배치 처리 시작

현재 배치에 있는 모든 적격 문서(이미 processing 또는 succeeded 상태가 아닌 문서)에 대한 추출을 시작합니다. 이 엔드포인트에서 실제로 크레딧이 사용됩니다. 계정이 모든 계정의 기본값인 Standard 모델 티어에 있는 경우 문서당 1크레딧이 사용됩니다. 계정에 Advanced 또는 Premium이 대신 할당된 경우 각 문서는 각각 3크레딧 또는 6크레딧이 소요됩니다. 티어는 추출을 실행하는 모델을 변경할 뿐, 반환되는 필드나 응답 형식은 변경하지 않으므로 이 엔드포인트의 다른 계약 조건은 변경되지 않습니다. 이 요청에는 tier 매개변수가 없습니다. 모델 티어는 호출자가 배치별로 선택하는 것이 아니라 ImageToTable.ai 팀이 할당하는 계정 수준 설정입니다. 이 엔드포인트가 호출되는 시점에 적용되는 티어가 청구되며, 계정의 티어가 완료 전에 변경되더라도 여기에서 대기열에 추가된 문서에는 해당 티어가 계속 적용됩니다. 여러 process 호출에 걸쳐 분할된 배치는 계정 티어가 그 사이에 변경된 경우 서로 다른 티어로 청구되는 문서를 가질 수 있습니다. 전체 설정 표는 계정 설정 및 API 동작을, 비표준 차감이 크레딧 원장에 표시되는 방식은 계정 사용량을 참조하세요.

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

매개변수

이름위치유형설명
batch_namepathstring처리할 배치입니다.
template_idbody (JSON)integer, 선택 사항적용할 저장된 템플릿입니다. 둘 다 제공된 경우 fields보다 우선합니다.
fieldsbody (JSON)array, 선택 사항이 실행에만 사용하는 임시 필드 목록 — [{"name": "...", "format_requirement": "..."}] 또는 이름 문자열의 일반 배열입니다. template_id가 제공되면 무시됩니다. 둘 다 생략하면 모델이 스스로 열을 추론합니다.
qualitybody (JSON)string, 선택 사항"fast" 또는 "high". 생략하면 계정의 thinking_type 설정으로 대체됩니다 — 계정 설정 및 API 동작을 참조하세요.
webhook_urlbody (JSON)string, 선택 사항같은 호출에서 이 배치의 완료 콜백을 등록(또는 업데이트)합니다 — 배치 Webhook 등록을 별도로 호출하는 것과 동일합니다. http:// 또는 https://여야 합니다.
Idempotency-Keyheader, 선택 사항string적극 권장됩니다 — 이 엔드포인트는 크레딧을 차감합니다. Idempotency를 참조하세요.

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

응답의 webhook_registered는 이 특정 호출만 반영합니다 — true가 되는 경우는 이 요청에 webhook_url이 포함된 경우뿐이며, 배치에 Webhook이 있는지 여부를 나타내는 것은 아닙니다. 이전에 배치 Webhook 등록을 통해 설정된(그리고 여기서 반복되지 않은) 배치는 완료 시 콜백이 정상적으로 실행되지만, 이 필드는 해당 호출에서 여전히 false로 반환됩니다 — 이미 BatchWebhook이 존재하는지 조회하지 않습니다. 여기서 false가 "이 배치에 Webhook이 실행되지 않음"을 의미한다고 생각하지 마세요.

이미 처리하고 알림을 받은 배치에 추가 문서를 업로드한 후 이 엔드포인트를 다시 호출하면, 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"에 해당하는 기능입니다. 요약 정보만 반환하며(document_count, 집계 status), 특정 배치의 전체 문서별 데이터는 배치 결과 가져오기를 사용하세요.

GET /api/v1/batches

매개변수

이름위치유형설명
sourcequery, 선택stringdirect, collect, email_inbox, api(POST /documents로 업로드, 메인 웹 앱의 direct와 구분됨) 또는 share(collect와 email_inbox를 모두 포함하는 별칭) 중 하나입니다. 모든 소스를 포함하려면 생략하세요.
qquery, 선택string배치 내 파일 이름에 대한 대소문자 구분 없는 부분 문자열 일치입니다.
date_fromquery, 선택string (YYYY-MM-DD)업로드 시간의 하한(포함)입니다.
date_toquery, 선택string (YYYY-MM-DD)업로드 시간의 상한(포함, 당일 종료 시점)입니다.
statusquery, 선택string필터링할 공개 상태의 쉼표로 구분된 목록(queued,processing,succeeded,failed,canceled)입니다.
template_idquery, 선택integer이 템플릿을 사용한 배치만 반환합니다.
modequery, 선택string이번 라운드에서 허용되는 값은 "table"뿐입니다(v1이 현재 지원하는 유일한 모드). 향후 추출 모드를 위해 예약되어 있습니다.
limitquery, 선택integer1–100. 기본값 20.
page_tokenquery, 선택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_namepathstring확인할 배치입니다.

가능한 오류

  • 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_namepathstring결과를 가져올 배치입니다.
includequery, optionalstring"bbox" — 설정하면 모든 필드 값이 일반 스칼라 대신 {"value": ..., "bbox": {...}|null}이 되고, 각 문서에는 bbox_status 필드가 추가됩니다. 아래를 참조하세요. 이는 절대 새 bbox 작업을 트리거하지 않으며, 이미 계산된 값만 반환합니다.

?include=bbox는 백필된 결과만 읽습니다. bbox 주석 트리거를 자동으로 호출하지 않습니다. 문서에 대해 bbox가 트리거된 적이 없다면(수동으로 또는 계정의 auto_annotate_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 문서로 된 테이블 데이터" 옵션이 없습니다. 알아두면 좋은 동작 차이 하나: 배치의 템플릿에 다중 페이지 병합이 구성된 경우, 이 엔드포인트는 항상 이를 적용합니다 — results와 달리 여기에는 제외 쿼리 매개변수가 없습니다. 스프레드시트 다운로드에는 기존 통합 호환성 문제를 보존할 필요가 없기 때문입니다.

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

매개변수

이름위치유형설명
batch_namepathstring내보낼 배치입니다.
formatquery, 선택 사항stringxlsx(기본값)만 허용됩니다.

응답은 파일 다운로드(Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)이며 JSON이 아닙니다 — 이 엔드포인트에는 응답 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_namepathstring삭제할 배치입니다.

가능한 오류

  • missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
  • batch_not_found — 다른 일부 리소스와 달리, 소유하지 않은(또는 존재하지 않는) batch_name을 삭제하면 조용히 무시되지 않고 404 오류가 반환됩니다.
📮 contact email: [email protected]