# 환경 설정 — API 키 및 클라이언트 설치

> 클라이언트를 설치하고, ImageToTable.ai API 키를 안전하게 저장하며, v1 API를 호출하기 전에 "요청을 보냈는데 오류가 발생했습니다"와 같은 가장 흔한 문제를 해결하는 방법을 알아봅니다.

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

## 클라이언트 설치

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

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

## Python 예제 사용하기

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

- **Python 3.8+** — `python3 --version`으로 확인하세요. 설치되어 있지 않다면 [python.org/downloads](https://www.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](https://nodejs.org/)에서 받으세요.
- 또는 **브라우저 DevTools 콘솔에 코드 조각을 붙여넣기**만 하면 됩니다. 모든 최신 브라우저는 동일한 API(`fetch`, `FormData`, `crypto.randomUUID()`)를 기본 지원하므로 설치가 전혀 필요 없습니다.

## API 키 받기

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

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

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

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

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

## 테스트 요청 보내기

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

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

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

## 문제 해결 체크리스트

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

- **`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` 필드를 전달하면 서버가 파일을 가져옵니다. 자세한 내용은 [빠른 시작](/developers/quickstart)을 참조하세요.
- **`rate_limit_exceeded` 오류가 발생하나요?** [속도 제한](/developers/guides/rate-limits)을 참조하세요. 제한은 계정별로 적용되며 요청 유형별이 아닙니다. 따라서 폴링 호출이 많으면 업로드 호출과 동일한 제한에 걸릴 수 있습니다.

---

Source: https://imagetotable.ai/ko/developers/environment-setup