시작하기

빠른 시작

이 문서는 키 발급, 문서 업로드, 처리 시작, 결과 수신까지의 전체 과정을 송장을 예시로 설명합니다. 아직 curl을 설치하지 않았거나 키에 대한 환경 변수를 설정하지 않았다면 먼저 환경 설정을 참조하세요.

1단계 — API 키 발급

API 키는 계정의 프로필 설정 페이지의 API Key 항목에서 확인할 수 있습니다. v1 API는 유료 요금제(기본 이상)가 필요합니다. 무료 요금제 키는 인증 검사를 통과하지만, 이후 모든 호출에서 plan_required 오류가 반환됩니다. 새로 생성되는 키는 itt_live_<16진수 64자> 형식입니다. 스크립트에 하드코딩되지 않도록 환경 변수로 내보내세요:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2단계 — 문서 업로드

POST /api/v1/documents는 file(멀티파트) 또는 서버가 대신 가져오는 url 중 하나를 받습니다. 둘 중 하나만 전달하세요. batch_name은 선택 사항입니다. 생략하면 API가 자동 생성하며(응답에 포함됨), 함께 처리하려는 모든 문서는 동일한 batch_name을 공유해야 합니다. 이 예제는 자체 사이트에 호스팅된 실제 샘플 송장에 대해 url을 사용하므로, 로컬 파일 없이도 그대로 실행 가능합니다:

curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

const response = await fetch("https://imagetotable.ai/api/v1/documents", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
  body: formData,
});
console.log(await response.json());

로컬 파일을 사용하시나요? url 대신 멀티파트 file 필드를 사용하세요. batch_name, template_id, password를 포함한 전체 매개변수 목록은 문서 업로드 참조를 확인하세요.

응답은 새 문서의 ID와 해당 문서가 속한 배치를 반환합니다. batch_name을 저장하세요. 다음 두 단계에서 필요합니다:

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}

이미지 대신 다중 페이지 PDF — 또는 Word(.docx)나 일반 텍스트(.txt) 파일(둘 다 서버 측에서 먼저 PDF로 변환됨)을 업로드해도 동일하게 작동합니다. 단, 각 페이지가 독립적으로 처리되므로 document_id가 페이지당 하나씩 배열로 반환됩니다.

3단계 — 처리 시작

POST /api/v1/batches/{batch_name}/process가 추출을 시작합니다. 저장된 템플릿을 template_id로 지정하거나, 여기처럼 fields로 원하는 필드를 인라인으로 선언하여 일회성 실행을 할 수 있습니다:

curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());

이렇게 하면 크레딧이 즉시 차감됩니다. 대부분의 계정은 대기열에 추가된 문서당 1크레딧이며, 더 높은 모델 티어가 할당된 계정은 더 많은 크레딧이 차감됩니다. 그런 다음 문서가 백그라운드 처리를 위해 대기열에 추가됩니다:

{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}

fields와 template_id를 완전히 생략하면 API가 대신 합리적인 열 이름을 자동으로 추론합니다. quality도 선택 사항입니다 — 생략하면 계정의 기본 속도/품질 설정으로 처리됩니다(계정 설정 및 API 동작 참조). 여기서 webhook_registered: false는 이 특정 호출에 webhook_url이 포함되지 않았다는 뜻일 뿐입니다 — 이 배치에 웹훅이 등록되지 않았다는 의미는 아닙니다. 별도로 PUT .../webhook을 통해 등록하는 경우 배치 참조를 확인하세요.

4단계 — 폴링하여 결과 가져오기

처리는 비동기식입니다 — all_done이 true가 될 때까지 GET /api/v1/batches/{batch_name}을 폴링하거나(단일 문서의 경우 몇 초), 폴링 대신 웹훅을 등록하세요. 전체 수명 주기는 비동기 작업 모델 가이드에서 다룹니다.

완료되면 재구성된 결과를 가져옵니다:

curl https://imagetotable.ai/api/v1/batches/260716-4K9P/results \
  -H "Authorization: Bearer $API_KEY"
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/results", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());

응답 JSON은 언어별로 달라지지 않습니다 — 어떤 클라이언트가 요청을 보냈는지에 따라 형태가 바뀌지 않습니다:

{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "merge_active": false,
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}

completed_at은 문서(또는 배치 수준에서는 배치의 모든 문서)가 succeeded, failed, 또는 canceled와 같은 최종 상태에 도달하면 설정됩니다. queued 또는 processing 상태에서는 null로 유지되며, 배치 수준에서는 일부 문서가 먼저 완료되었더라도 배치의 모든 문서가 완료될 때까지 null로 유지됩니다.

다음 단계

여기서부터: 비동기 작업 모델에서 전체 상태 수명 주기를 확인하고, 웹훅으로 폴링 대신 알림을 받거나, API 참조에서 모든 엔드포인트의 전체 매개변수 목록을 확인하세요.

📮 contact email: [email protected]