계정 설정 및 API 동작
계정의 일부 동작은 한 번만 구성됩니다. 대부분은 웹 앱의 프로필 설정 페이지에서, 한 가지 예외(아래의 모델 티어)는 ImageToTable.ai 팀을 통해서만 구성되며, 이 API를 통해서는 구성되지 않습니다. 이 페이지에서는 이러한 각 설정이 v1에 어떻게 반영되는지, 즉 API가 해당 설정을 무조건 따르는지 아니면 요청별로 재정의할 수 있는지 정확히 설명합니다. 이 내용은 의도적으로 개별 엔드포인트 문서에 분산하지 않고 여기에 모았습니다. 한 번에 하나의 엔드포인트 참조 페이지만 읽으면 놓치기 쉬운 교차 적용 동작이기 때문입니다.
일반 규칙
v1은 계정의 현재 구성을 직접 읽어 적용합니다. 별도의 API 계층 구성 시스템은 없으며, (아래의 의도된 예외 하나를 제외하고) 단일 요청에 대해 계정 설정을 재정의할 방법도 없습니다. 이는 의도적인 설계입니다. 동일한 동작을 구성하는 두 개의 독립된 장소(웹 앱과 병렬 API 구성)를 유지하면 필연적으로 동기화가 어긋나게 되며, 목표는 웹 앱, 이 API, 또는 Google Sheets 애드온 중 어떤 표면에서 처리를 시작했든 동일한 계정이 동일하게 동작하도록 하는 것입니다.
설정 및 API 동작
| 설정 | 웹 앱 동작 | v1 API 동작 | 요청별 재정의 가능? |
|---|---|---|---|
bbox 자동 주석auto_annotate_bbox | 계정 수준 토글입니다. 켜면 완료된 모든 추출에 대해 유료 bbox 주석 패스가 자동으로 실행됩니다. | 정확히 따릅니다 — v1을 통해 생성 및 처리된 배치는 예외 없이 이 토글을 따릅니다. 켜져 있으면 직접 POST /documents/{document_id}/bbox를 호출하지 않아도 bbox 주석에 대해 청구될 수 있습니다. | 아니요. 요청 수준에서 건너뛰거나 강제할 방법이 없습니다. |
처리 품질thinking_type | 처리 속도/품질 티어를 선택하는 계정 수준 설정입니다. | 위 규칙의 유일한 예외입니다. POST /batches/{batch_name}/process에서 quality를 생략하면 계정의 현재 설정으로 대체됩니다 — 웹 앱과 동일한 동작입니다. 하지만 해당 요청에서 quality: "fast" 또는 quality: "high"를 전달하여 해당 호출에만 재정의할 수도 있습니다. | 예 — 이 페이지에서 요청별로 재정의할 수 있는 유일한 설정입니다. |
데이터 보존auto_delete / auto_delete_after | 처리 후 N일이 지나면 원본 이미지를 자동으로 삭제하는 계정 수준 설정입니다. | 정확히 따릅니다 — v1을 통해 생성된 문서는 웹 앱을 통해 업로드된 모든 항목과 동일한 보존 정책을 따릅니다. | 아니요. |
| 처리 모드 (내부 rec_mode, mode로 노출됨) | 웹 앱은 현재 테이블 형식 추출과 전체 문서 Word 변환을 지원합니다. | v1은 현재 mode=table(구조화된 필드 추출)만 지원합니다. 전체 문서 변환은 계획되어 있지만 아직 API를 통해 제공되지는 않습니다. | 아직 해당 없음 — 선택할 값이 하나뿐입니다. 더 많은 모드가 출시되면 이는 동작 변경이 아닌 순수한 추가가 될 것입니다. |
모델 티어model_tier | 계정의 추출이 실행되는 AI 모델과 처리된 각 문서의 비용을 나타냅니다: Standard(모든 계정의 기본값, 1크레딧), Advanced(3크레딧), Premium(6크레딧). ImageToTable.ai 팀이 지정하며, 계정 설정에는 티어 선택기가 없습니다. | 정확히 따릅니다. POST /batches/{batch_name}/process는 계정의 현재 티어 비용에 따라 크레딧을 차감하며, 단일 호출에 대해 다른 티어를 요청할 방법은 없습니다. 티어는 해당 엔드포인트가 호출되는 시점에 고정됩니다. 이미 대기 중인 문서는 계정 티어가 처리 완료 전에 변경되더라도 청구된 티어(및 크레딧 비용)를 유지하며, 이후 취소되거나 실패할 경우에도 동일하게 고정된 티어로 환불됩니다. 비Standard 요금이 크레딧 원장에 표시되는 방식은 계정 사용량을 참조하세요. | 아니요. 이 페이지의 다른 모든 행보다 엄격합니다. 웹 앱의 셀프 서비스 계정 설정조차 아니므로 요청별로 읽고 반영할 항목이 없습니다. v1에는 어디에도 티어 매개변수가 없습니다. |
요청 수준 재정의를 추가하지 않는 이유는?
bbox 자동 주석과 보존 정책은 호출별 기본 설정이 아닌 계정 수준의 거버넌스로 취급됩니다. 이는 '모든 항목에 켜기 또는 모든 항목에 끄기' 스위치와 같은 종류로, 단일 API 호출이 계정의 기존 구성에서 조용히 벗어나도록 허용하면 이 설계가 피하려는 두 구성 소스 간 불일치 문제가 정확히 발생합니다. quality는 다릅니다. 어떤 속도/품질 티어가 적합한지는 호출마다 실제로 달라질 수 있으므로(이 배치는 빠르게 처리해야 하고, 저 배치는 최대 정확도가 필요함), 거버넌스 설정이 아닌 운영상의 선택으로 취급되며 유일한 재정의 항목으로 열려 있습니다.
모델 티어는 '요청별 재정의 없음'보다 한 단계 더 나아갑니다. 셀프 서비스 계정 설정조차 아닙니다. 이 페이지의 다른 행은 프로필 설정 페이지에서 직접 구성하고 v1이 단순히 미러링하는 항목입니다. 모델 티어는 계정이 실제로 실행 중인 워크로드를 기반으로 ImageToTable.ai 팀이 할당하는 요금으로, 각 문서의 비용을 직접 변경합니다. 호출자가 요청별로(또는 계정별로, 지원 없이) 변경할 수 있는 항목으로 노출하면, 잘못된 값 하나가 확인 단계 없이 배치 청구서를 3배 또는 6배로 조용히 늘릴 수 있습니다. 이는 이 페이지의 나머지 부분이 피하는 동일한 불일치 문제의 크레딧-실제-화폐 버전입니다.