시작하기

환경 설정

이 페이지는 터미널에서 HTTP API를 호출해 본 적이 없는 분들을 위한 것입니다. curl과 환경 변수에 이미 익숙하다면 빠른 시작으로 바로 넘어가세요.

클라이언트 설치

사용자 정의 헤더로 HTTP 요청을 보낼 수 있는 도구가 필요합니다. 두 가지 일반적인 옵션은 다음과 같습니다:

  • curl — 명령줄 도구로, 보통 macOS와 Linux에 이미 설치되어 있습니다. 터미널에서 curl --version으로 확인하세요. Windows에서는 curl.se/windows에서 설치하거나 Git Bash / WSL에 번들된 curl을 사용하세요. 이 문서의 모든 예제는 먼저 curl 명령어로 작성됩니다.
  • Postman — 요청을 작성하고 저장하기 위한 그래픽 앱으로, 셸 명령어를 작성하는 대신 양식을 클릭하여 작업하는 것을 선호하는 경우 유용합니다. postman.com/downloads에서 설치한 후, URL, 메서드, 헤더, 본문을 새 요청에 복사하여 이 사이트의 모든 curl 예제를 재현할 수 있습니다.

Python 예제 사용하기

이 사이트의 모든 코드 샘플에는 널리 사용되는 requests 라이브러리를 기반으로 한 Python 탭이 있습니다. 공식 ImageToTable.ai SDK는 아닙니다. 필요한 것은 다음과 같습니다:

  • Python 3.8+ — python3 --version으로 확인하세요. 설치되어 있지 않다면 python.org/downloads에서 받으세요.
  • requests — 표준 라이브러리에 포함되어 있지 않으므로 먼저 설치하세요:
    pip install requests
    .

다운로드한 파일(xlsx/docx)을 파싱하는 내보내기 예제는 openpyxl / python-docx도 사용합니다. 해당 특정 예제를 따라가는 경우에만 필요하며, pip install openpyxl python-docx로 설치하세요.

JavaScript 예제 사용하기

JavaScript 탭은 기본 fetch API를 사용하므로 별도 라이브러리 설치가 필요하지 않지만, 비교적 최신 런타임을 가정합니다:

  • Node.js 20+ — node --version으로 확인하세요. 예제는 최상위 await와 전역 crypto.randomUUID()를 사용하므로 최신 Node가 필요합니다. Node 18에서는 crypto가 CommonJS/REPL 외부에서 안정적으로 전역으로 제공되지 않아, API 키와 무관한 혼란스러운 crypto is not defined 오류가 발생할 수 있습니다. 최신 버전은 nodejs.org에서 받으세요.
  • 또는 브라우저 DevTools 콘솔에 코드 조각을 붙여넣기만 하면 됩니다. 모든 최신 브라우저는 동일한 API(fetch, FormData, crypto.randomUUID())를 기본 지원하므로 설치가 전혀 필요 없습니다.

API 키 받기

API 키는 계정의 프로필 설정 페이지에서 발급받습니다. v1 API는 유료 플랜에서 사용 가능합니다. Free 플랜 키로 호출하면 인증 오류 대신 plan_required 오류가 반환됩니다. 키 자체는 유효하지만 아직 v1 사용이 허용되지 않았기 때문입니다.

API 키를 환경 변수로 저장하기

공유하거나, 스크린샷을 찍거나, 버전 관리에 커밋할 수 있는 명령어에 키를 직접 붙여넣지 마세요. 대신 셸 세션에 내보내기(export)한 후 모든 요청에서 $API_KEY로 참조하세요. 이 사이트의 모든 예제는 이 변수가 존재한다고 가정합니다:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

이 설정은 현재 터미널 세션에서만 유지됩니다. 영구적으로 적용하려면 셸 시작 파일에 같은 줄을 추가하세요. 또는 스크립트를 작성하는 경우 소스 코드에 하드코딩하지 말고 .env 파일이나 비밀 관리자에서 로드하세요.

테스트 요청 보내기

실제 문서로 넘어가기 전에 키와 설정이 제대로 작동하는지 확인하세요.

curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

유료 플랜의 작동하는 키는 계정 스냅샷을 반환합니다. 그 외의 경우 아래 문제 해결 체크리스트를 참조하세요.

문제 해결 체크리스트

모든 v1 오류는 type/code/message가 포함된 JSON으로 반환됩니다. 전체 목록은 오류 처리 가이드를 참조하세요. 요청이 작동하지 않을 때 가장 먼저 확인해야 할 사항은 다음과 같습니다.

  • missing_api_key 오류가 발생하나요? 헤더가 정확히 Authorization: Bearer <key>인지 확인하세요. Bearer 단어, 공백 하나, 그 다음 키 순서여야 합니다. 공백이 누락되거나 $API_KEY에 따옴표 문자가 잘못 들어가면 이 오류가 발생합니다.
  • invalid_api_key 오류가 발생하나요? 키가 계정과 일치하지 않거나 계정이 비활성화된 경우입니다. 프로필 페이지에서 키를 다시 복사하세요. 키는 길어서 복사-붙여넣기 시 잘릴 수 있습니다.
  • plan_required 오류가 발생하나요? 키는 유효하지만 계정이 Free 플랜입니다. v1을 사용하려면 Basic 이상으로 업그레이드하세요.
  • JSON 응답이 아닌 연결 오류가 발생하나요? URL이 https://imagetotable.ai/api/v1/로 시작하는지, 그리고 해당 엔드포인트에 필요한 경우 -X POST를 사용하고 있는지 다시 확인하세요. POST 전용 엔드포인트에 GET 요청을 보내면 라우트에 도달하지 않습니다.
  • 파일 업로드 중 예상치 못한 오류가 발생하나요? 멀티파트 파일 업로드는 -F "file=@/path/to/file.jpg"를 사용해야 하며, -d나 원시 JSON 본문을 사용하면 안 됩니다. 이 둘을 혼동하는 것이 가장 흔한 업로드 실수입니다. 앞에 붙은 @는 curl에게 해당 경로를 사용자 컴퓨터의 실제 파일로 읽도록 지시합니다. URL이 아니며, 명령을 실행하기 전에 파일이 이미 존재해야 합니다. 로컬 파일이 없다면 이 부분을 건너뛰고 file 대신 url 필드를 전달하면 서버가 파일을 가져옵니다. 자세한 내용은 빠른 시작을 참조하세요.
  • rate_limit_exceeded 오류가 발생하나요? 속도 제한을 참조하세요. 제한은 계정별로 적용되며 요청 유형별이 아닙니다. 따라서 폴링 호출이 많으면 업로드 호출과 동일한 제한에 걸릴 수 있습니다.
📮 contact email: [email protected]