Documents

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

문서 업로드

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

POST /api/v1/documents

매개변수

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

PDF 업로드는 단일 ID가 아닌 배열을 반환합니다. PDF를 업로드하면 모든 페이지가 자체 Document로 렌더링되며 응답의 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, 50페이지 제한을 초과한 PDF, 변환에 실패한 .docx/.txt 파일.
invalid_parameter (param: "url") — file과 url이 모두 전송되었거나, URL이 공개 주소로 확인되지 않거나, 다운로드 실패/시간 초과, 또는 다운로드한 파일이 30MB를 초과합니다.
invalid_parameter (param: "batch_name") — 배치가 이미 요금제의 최대 배치 크기에 도달했습니다.
invalid_parameter (param: "template_id") 또는 template_not_found.
rate_limit_exceeded — 계정에 이미 처리되지 않은 문서가 너무 많습니다. 먼저 일부를 처리하거나 삭제하세요.

문서 가져오기

단일 문서의 현재 상태와, 추출이 성공한 후 재구성된 line_items를 가져옵니다. 이는 배치 결과 가져오기의 단일 문서 버전입니다 — 동일한 재구성 규칙을 따르지만 ?include=bbox 옵션은 없습니다.

GET /api/v1/documents/{document_id}

매개변수

이름	위치	유형	설명
`document_id`	path	string	`POST /documents`에서 반환된 문서 ID입니다.

status는 항상 queued, processing, succeeded, failed, canceled 중 하나입니다 — 상태 머신에 대한 자세한 내용은 비동기 모델 가이드를 참조하세요. completed_at은 문서가 최종 상태에 도달하면 설정되며, 그 전까지는 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 작업에 관한 것이며, 추출 작업에 관한 것이 아닙니다. 어느 경우든, 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입니다. 이는 정상적이고 일반적인 응답이며 오류가 아닙니다.

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

매개변수

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

rows는 행 인덱스를 필드 이름 → 정규화된 bbox 객체의 맵에 매핑합니다. 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 } } }