Documents

Document는 처리된 단일 페이지입니다 — 업로드된 이미지 또는 업로드된 PDF에서 렌더링된 한 페이지입니다. 모든 Document는 Batch에 속하며 (batch_name으로 식별), 실제로 처리를 시작하는 단위입니다. 다중 페이지 PDF를 업로드하면 동일한 배치에 페이지당 하나의 Document가 생성됩니다 — 아래의 문서 업로드를 참조하세요.

문서 업로드

단일 파일(이미지, PDF, Word 또는 일반 텍스트)을 배치에 업로드합니다. batch_name을 생략하면 자동으로 생성되어 응답에 반환됩니다. 업로드는 추출을 시작하지 않습니다 — 함께 처리하려는 모든 항목을 업로드한 후 배치 처리 시작을 호출하세요. 응답의 remaining_batch_capacity는 이 배치가 플랜의 최대 배치 크기(Account의 max_batch_size 참조)에 도달하기 전에 추가로 수용할 수 있는 문서 수를 알려줍니다 — 별도의 조회 없이 클라이언트 측에서 이 배치에 계속 추가할지 새 배치를 시작할지 결정하는 데 유용합니다.

POST /api/v1/documents

파라미터

이름	위치	유형	설명
`file`	body (multipart)	file	`url`이 제공되지 않은 경우 필수입니다. 이미지(JPEG/PNG 등), PDF, Word 문서(`.docx`만 지원 — 레거시 `.doc` 바이너리 형식은 지원되지 않으므로 먼저 `.docx`로 저장), 또는 일반 텍스트 파일(`.txt`). PDF는 업로드당 최대 50페이지로 제한되며 페이지당 하나의 문서로 분할됩니다. `.docx`/`.txt`는 서버에서 먼저 PDF로 변환된 후 동일한 페이지별 분할 규칙을 따릅니다.
`url`	body (multipart)	string, optional	`file`의 대안 — 파일을 첨부할 필요 없이 서버가 이 URL에서 파일을 다운로드합니다. `file`과 상호 배타적이며 정확히 하나만 전달해야 합니다. 공개 `http://` 또는 `https://` URL이어야 하며(localhost/사설 네트워크 주소는 불가), 다운로드는 30MB로 제한되고 15초 읽기 시간 제한이 적용됩니다.
`batch_name`	body (multipart)	string, optional	이 문서를 추가할 배치입니다. 최대 50자. 생략하면 새 배치 이름이 자동 생성됩니다(응답에 반환). 여러 업로드에 동일한 값을 재사용하여 처리 전에 하나의 배치를 구성할 수 있습니다.
`template_id`	body (multipart)	integer, optional	계정에 속한 템플릿 ID로 이 문서와 사전 연결할 수 있습니다. 필수는 아닙니다 — `process` 호출 시 템플릿(또는 임시 필드)을 전달할 수도 있습니다.
`password`	body (multipart)	string, optional	PDF 전용. 파일이 암호로 보호된 경우 먼저 시도됩니다. 생략되거나 파일을 잠금 해제하지 못하면 계정의 Email Inbox 설정에 저장된 암호로 대체됩니다 — 이 필드는 Email Inbox가 설정되어 있지 않아도 되며, 단지 호출별 대안입니다.
`Idempotency-Key`	header, optional	string	재시도해도 안전합니다. 멱등성 참조.

PDF(및 변환된 Word/텍스트) 업로드는 단일 ID가 아닌 배열을 반환합니다. PDF를 업로드하면 모든 페이지가 각각의 문서로 렌더링되며 응답의 document_id는 JSON 배열(페이지 순서대로 페이지당 하나의 문자열)이 되고 page_count 필드도 함께 반환됩니다. 여러 페이지로 변환되는 .docx/.txt 업로드도 변환 결과 PDF 바이트가 생성된 후 동일한 코드 경로로 분할되므로 동일하게 동작합니다. 단일 이미지 업로드는 스칼라 문자열을 반환합니다. document_id가 항상 문자열이라고 가정하는 클라이언트 코드는 다중 페이지 업로드에서 오류가 발생합니다 — 전송하는 파일이 여러 페이지를 생성할 수 있는지 확인하고 응답 형태에 따라 분기하거나, 항상 이미지를 전송하고 스칼라 케이스에 의존하지 않아야 합니다. 오른쪽의 두 응답 예시를 참조하세요.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
missing_parameter — file도 url도 전송되지 않았습니다.
invalid_parameter (param: "file") — 잘못되었거나 손상된 이미지 또는 PDF, 잠금 해제에 실패한 암호 보호 PDF(password 필드나 저장된 Email Inbox 비밀번호가 모두 작동하지 않음), 50페이지 제한을 초과한 PDF, 또는 변환에 실패한 .docx/.txt 파일(지원되지 않는 레거시 .doc 파일 포함 — 먼저 .docx로 저장하세요)입니다.
invalid_parameter (param: "url") — file과 url이 모두 전송되었거나, URL이 공개 주소로 확인되지 않거나, 다운로드가 실패했거나 시간 초과되었거나, 다운로드된 파일이 30MB를 초과합니다.
invalid_parameter (param: "batch_name") — 배치가 이미 플랜의 최대 배치 크기에 도달했거나, 이름이 50자를 초과합니다.
invalid_parameter (param: "template_id") 또는 template_not_found.
rate_limit_exceeded — 계정에 처리되지 않은(queued) 문서가 이미 너무 많습니다. 먼저 처리하거나 삭제하세요.

문서 가져오기

단일 문서의 현재 상태를 가져오고, 추출이 성공하면 재구성된 line_items를 가져옵니다. 이는 배치 결과 가져오기의 단일 문서 버전입니다 — 동일한 재구성 규칙을 따르지만 ?include=bbox 옵션은 없습니다(해당 옵션은 배치 수준 결과 엔드포인트에만 있습니다).

GET /api/v1/documents/{document_id}

매개변수

이름	위치	유형	설명
`document_id`	path	string	`POST /documents`가 반환한 문서 ID입니다(PDF 페이지의 경우 해당 배열의 항목 중 하나).

status는 항상 queued, processing, succeeded, failed, canceled 중 하나입니다 — 상태 머신에 대한 자세한 내용은 비동기 모델 가이드를 참조하세요. completed_at은 문서가 최종 상태(succeeded, failed, 또는 canceled)에 도달하면 설정되며, 그 이전에는 null로 유지됩니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
document_not_found — 계정에 해당 ID의 문서가 없습니다.

문서 이미지 가져오기

문서의 페이지 이미지를 반환합니다. 기본적으로 전체 페이지이며, ?crop=을 사용하면 정규화된 영역을, ?size=thumb을 사용하면 미리 생성된 작은 썸네일을 반환하여 목록/그리드 로딩 속도를 높입니다. ?crop=은 순수 위치 필드의 image_url을 지원합니다(배치 결과 가져오기 참조). 직접 좌표를 지정하여 호출할 수도 있습니다.

GET /api/v1/documents/{document_id}/image

매개변수

이름	위치	유형	설명
`document_id`	path	string	문서 ID입니다.
`crop`	query, 선택 사항	string	`"x1,y1,x2,y2"` — API의 다른 모든 `bbox` 객체와 동일한 정규화된 좌표 규칙을 따르는 0과 1 사이의 네 개의 부동 소수점입니다. 생략하면 전체 페이지 이미지를 가져옵니다.
`size`	query, 선택 사항	string	`thumb`을 전달하면 전체 해상도 페이지 대신 미리 생성된 작은 버전을 가져옵니다. `crop`도 함께 제공된 경우 무시됩니다. 이 문서에 대해 썸네일이 생성되지 않은 경우(작은 이미지는 항상 썸네일을 만들 가치가 없음) 전체 이미지로 대체되며, 오류가 발생하지 않습니다.

응답은 JSON이 아닌 원시 이미지 바이트(Content-Type: image/jpeg)입니다. 이 엔드포인트의 오른쪽에는 응답 JSON 예제가 없으며, 요청만 있습니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
document_not_found — 해당 ID의 문서가 없거나, 원본 이미지 파일을 더 이상 사용할 수 없습니다(예: 계정의 자동 삭제 보존 기간이 지난 경우).
invalid_parameter (param: "crop") — crop 값 형식 오류, 좌표가 0–1 범위를 벗어났거나, 이미지 경계에 클리핑된 후 빈 자르기 영역이 발생한 경우입니다.

bbox 주석 트리거

추출된 각 필드의 값이 페이지에서 물리적으로 위치하는 곳을 찾는 선택적 유료 2차 작업을 명시적으로 시작합니다. 이는 추출 자체와는 별개의 과금 대상 작업입니다. 이 엔드포인트를 연결하기 전에 경계 상자 가이드, 특히 계정의 auto_annotate_bbox 설정이 이 엔드포인트를 호출하지 않고도 동일한 작업을 자동으로 트리거(및 과금)할 수 있다는 내용을 먼저 확인하세요.

POST /api/v1/documents/{document_id}/bbox

매개변수

이름	위치	유형	설명
`document_id`	path	string	추출된 데이터가 있는 `succeeded` 상태의 문서여야 합니다. 추출이 완료되지 않은 문서에는 주석을 추가할 수 없습니다.
`Idempotency-Key`	header, optional	string	권장됩니다. 이 작업은 크레딧을 사용합니다. 멱등 키를 참조하세요.

새 bbox 작업이 대기열에 추가된 경우 202를 반환하고, 이 문서에 대한 bbox 작업이 이미 실행 중인 경우(already_running: true) 200을 반환합니다. 즉, 이전에 이 문서에 대해 동일한 엔드포인트를 이미 호출했으며 해당 이전 bbox 작업이 아직 완료되지 않았음을 의미합니다. 이는 문서 자체의 추출 완료 여부와는 무관합니다. bbox는 이미 succeeded 상태인 문서에서만 트리거할 수 있으므로(아래 "가능한 오류" 참조), 이 엔드포인트를 호출할 수 있는 시점에는 이미 추출이 완료되어 있습니다. already_running은 전적으로 동일 문서에 대한 두 번째 bbox 작업에 관한 것이며, 추출 작업에 관한 것이 아닙니다. 어느 경우든(202 또는 200), 200 경로에서는 새로운 작업이 시작되거나 청구되지 않습니다. 반환된 group_batch_id로 bbox 주석 가져오기를 폴링하여 결과를 확인하세요.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
document_not_found — 계정에 이 ID를 가진 문서가 없습니다.
insufficient_credits — 이 주석 패스를 실행하기에 크레딧이 부족합니다.
invalid_parameter — 문서가 아직 이 작업을 수행하기에 유효한 상태가 아니거나(처리 중), 상자를 찾을 추출된 데이터가 없습니다.

bbox 주석 가져오기

문서에 대해 트리거된 가장 최근 bbox-annotation 작업의 상태를 폴링하고 결과를 가져옵니다. 이 문서에 대해 작업이 한 번도 트리거된 적이 없으면 exists는 false이고 status/group_batch_id는 null입니다. 이는 정상적이고 일반적인 응답(대부분의 문서에서 bbox가 전혀 트리거되지 않음)이며 오류가 아닙니다.

GET /api/v1/documents/{document_id}/bbox

매개변수

이름	위치	유형	설명
`document_id`	path	string	문서 ID입니다.

rows는 행 인덱스(문자열, 예: "0")를 필드 이름 → 정규화된 bbox 객체(해당 필드의 위치가 페이지에서 발견되지 않은 경우 null)의 맵에 매핑합니다. status는 API의 다른 모든 곳과 동일한 5개 값의 폐쇄형 열거형을 사용합니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
document_not_found — 계정에 이 ID를 가진 문서가 없습니다.

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, files={"file": open("invoice.jpg", "rb")}, data={"batch_name": "july-invoices"}, ) print(response.json())

import { readFile } from "node:fs/promises"; const formData = new FormData(); formData.append("file", new Blob([await readFile("invoice.jpg")]), "invoice.jpg"); formData.append("batch_name", "july-invoices"); const response = await fetch("https://imagetotable.ai/api/v1/documents", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, body: formData, }); console.log(await response.json());

curl -X POST https://imagetotable.ai/api/v1/documents \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "url=https://imagetotable.ai/static/samples/invoice.webp" \ -F "batch_name=july-invoices"

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, data={ "url": "https://imagetotable.ai/static/samples/invoice.webp", "batch_name": "july-invoices", }, ) print(response.json())

{ "document_id": [ "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p1", "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p2" ], "batch_name": "july-invoices", "page_count": 2, "remaining_batch_capacity": 198 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "batch_name": "july-invoices", "filename": "invoice_042.jpg", "status": "succeeded", "created_at": "2026-07-16T09:12:03+00:00", "started_at": "2026-07-16T09:12:05+00:00", "completed_at": "2026-07-16T09:12:14+00:00", "line_items": [ { "invoice_number": "INV-1042", "invoice_date": "2026-07-01", "total_amount": "1,204.50" } ] }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) with open("page.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("page.jpg", Buffer.from(await response.arrayBuffer()));

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"crop": "0.10,0.08,0.42,0.30"}, ) with open("crop.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const url = new URL("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image"); url.searchParams.set("crop", "0.10,0.08,0.42,0.30"); const response = await fetch(url, { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("crop.jpg", Buffer.from(await response.arrayBuffer()));

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json());

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "exists": true, "status": "succeeded", "group_batch_id": "bx_8a3c2e1f", "rows": { "0": { "invoice_number": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}, "total_amount": null } } }

시작하기

가이드

API 참조

더보기

Documents

문서 업로드

파라미터

가능한 오류

문서 가져오기

매개변수

가능한 오류

문서 이미지 가져오기

매개변수

가능한 오류

bbox 주석 트리거

매개변수

가능한 오류

bbox 주석 가져오기

매개변수

가능한 오류