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

PDF 업로드는 단일 ID가 아닌 배열을 반환합니다. PDF를 업로드하면 각 페이지가 자체 문서로 렌더링되며, 응답의 document_id는 JSON 배열과 page_count 필드가 됩니다. 단일 이미지 업로드는 스칼라 문자열을 반환합니다. document_id가 항상 문자열이라고 가정하는 클라이언트 코드는 PDF 업로드에서 중단됩니다. 보내는 파일이 PDF인지 확인하고 응답 형태에 따라 분기하거나, 항상 이미지를 보내고 스칼라 경우에 의존하지 마세요. 오른쪽의 두 응답 예시를 참조하세요.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
missing_parameter — file과 url 중 어느 것도 전송되지 않았습니다.
invalid_parameter (param: "file") — 잘못되었거나 손상된 이미지/PDF, 잠금 해제할 수 없는 암호 보호 PDF, 또는 30페이지 제한을 초과한 PDF입니다.
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=을 사용하면 정규화된 크롭 이미지를 반환합니다. 이는 순수 위치 필드의 image_url을 제공하는 기능입니다(배치 결과 가져오기 참조). 직접 좌표를 지정하여 호출할 수도 있습니다.

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

매개변수

이름	위치	유형	설명
`document_id`	path	string	문서 ID입니다.
`crop`	query, 선택 사항	string	`"x1,y1,x2,y2"` — 0과 1 사이의 네 개의 부동 소수점 값으로, API의 다른 모든 `bbox` 객체와 동일한 정규화된 좌표 규칙을 따릅니다. 생략하면 전체 페이지 이미지를 반환합니다.

응답은 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차 작업을 명시적으로 시작합니다. 이는 추출 자체와는 별개의 청구 가능한 작업입니다. 이 엔드포인트를 연결하기 전에 Bounding Boxes 가이드, 특히 계정의 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 } } }