# 빠른 시작

첫 API 요청을 보내고 Excel 파일을 다운로드하세요.

공식 문서: https://img2excel.net/ko/docs/api/getting-started

IMG2Excel API는 표 이미지를 편집 가능한 Excel 통합 문서로 변환합니다. 동기 엔드포인트 사용을 권장합니다. 이미지를 업로드하고 변환이 완료되면 응답의 URL에서 XLSX 파일을 다운로드하세요. 비동기 엔드포인트도 계속 사용할 수 있습니다.

| 항목 | 값 |
| --- | --- |
| 기본 URL | `https://img2excel.net` |
| 인증 | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| API 이용 조건 | Business 또는 Professional 크레딧 패키지 구매 |
| 입력 | PNG, JPG 또는 JPEG 이미지 1개, 최대 4MB |
| 출력 | 편집 가능한 `.xlsx` 파일 |

## 1. API 키 설정

[API 설정](https://img2excel.net/ko/settings/api)에서 키를 복사하고 서버의 환경 변수에 저장하세요.

```bash
export IMG2EXCEL_API_KEY="your_api_key"
```

API 키를 안전하게 보관하세요. 브라우저에서 실행되는 코드나 공개 저장소에 포함하지 마세요.

## 2. 표 이미지 업로드

이미지에 맞는 엔드포인트를 선택하세요.

| 이미지 | 엔드포인트 |
| --- | --- |
| 인쇄된 표, 스크린샷 또는 스캔한 스프레드시트 | [이미지를 Excel로 변환](https://img2excel.net/ko/docs/api/image-to-excel) |
| 손글씨 표, 일지 또는 기록 | [손글씨를 Excel로 변환](https://img2excel.net/ko/docs/api/handwriting-to-excel) |

다음 예제는 인쇄된 표를 전송합니다. `table.png`를 이미지 경로로 바꾸세요. 손글씨는 `/api/v1/handwriting-to-excel`을 사용하세요.

```bash
curl --fail-with-body --max-time 330 -i https://img2excel.net/api/v1/image-to-excel \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY" \
  -H "Idempotency-Key: table-import-001" \
  -F "file=@table.png"
```

새 이미지마다 다른 `Idempotency-Key`를 사용하세요. 같은 업로드를 재시도할 때만 같은 값을 사용하세요.

동기 요청은 변환 완료 후 **200 OK**와 `result.download_url`을 반환합니다. 아래 URL은 예시이므로 실제 응답의 URL을 사용하세요.

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:08.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}
```

동기 엔드포인트는 변환 완료까지 기다립니다. HTTP 클라이언트 타임아웃을 330초로 설정하세요. 연결 시간이 초과되면 같은 `Idempotency-Key`로 재시도하세요. 새 키는 새 변환을 시작합니다.

## 3. Excel 파일 다운로드

성공 응답의 `result.download_url`을 복사하세요.

```bash
curl --fail --location "PASTE_RESULT_DOWNLOAD_URL_HERE" --output table.xlsx
```

다운로드 URL은 15분간 유효합니다. 결과는 완료 후 24시간 보관됩니다. 이 기간에 작업을 다시 조회하면 새 URL을 받을 수 있습니다. 변환 실패 시 크레딧은 차감되지 않습니다.

## 비동기 변환 (선택 사항)

백그라운드 처리는 변환 엔드포인트 뒤에 `/jobs`를 추가하세요. 새 작업은 `202`, 작업 ID, `Location` 헤더를 반환합니다. 해당 URL을 2~3초마다 조회하고 `succeeded`, `failed` 또는 `expired`가 되면 중지하세요. 폴링 예제는 [작업 및 오류](https://img2excel.net/ko/docs/api/jobs)를 참조하세요.

동기 변환 실패 시 `422`, `error.code`, `error.message`가 반환됩니다. 같은 멱등성 키로 재시도하면 원래 작업을 반환합니다. 작업이 진행 중이면 `202`를 반환하므로 `Location` URL을 조회하세요. 결과가 만료되면 `410`을 반환합니다.

## AI 코딩 도우미 사용

위의 **AI용 복사**를 선택하고 ChatGPT, Claude, Gemini, Cursor 또는 다른 도우미에 지침을 붙여 넣으세요. 서버에서 사용하는 언어와 인쇄된 표인지 손글씨 표인지 알려주세요. 각 엔드포인트 페이지에도 복사 기능과 Python / Node.js 예제가 있습니다.

전체 API 정의는 [OpenAPI 명세](https://img2excel.net/api/openapi.json) 또는 [전체 API 문서](https://img2excel.net/ko/docs/api/text/llms-full.txt)를 참조하세요.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
전체 API 문서: https://img2excel.net/ko/docs/api/text/llms-full.txt