# 이미지를 Excel로 변환

스크린샷, 스캔 문서 또는 사진의 인쇄된 표를 편집 가능한 XLSX 통합 문서로 변환합니다.

공식 문서: https://img2excel.net/ko/docs/api/image-to-excel

`POST /api/v1/image-to-excel`

스크린샷, 스캔 문서 또는 사진의 인쇄된 표를 편집 가능한 XLSX 통합 문서로 변환합니다. 동기 엔드포인트는 변환 완료까지 기다립니다. 변환 실패 시 크레딧은 차감되지 않습니다.

## 요청

### 요청 헤더

| 헤더 | 필수 | 설명 |
| --- | --- | --- |
| `Authorization` | 예 | `Bearer $IMG2EXCEL_API_KEY`. 서버의 API 키를 사용하세요. |
| `Content-Type` | 예 | boundary가 포함된 `multipart/form-data`. 파일 전송 시 HTTP 클라이언트가 자동으로 설정하도록 하세요. |
| `Idempotency-Key` | 아니요 | 최대 200자의 멱등성 키. 업로드마다 지정하는 것을 권장하며, 같은 업로드 재시도 시 같은 값을 사용합니다. |

### 요청 본문

| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `file` | 바이너리 파일 | 예 | PNG, JPG 또는 JPEG 이미지 1개, 최대 4MB. |

JSON 본문이나 이미지 URL 대신 파일 업로드로 전송하세요. 인식 설정은 엔드포인트에서 자동으로 선택합니다.

## 요청 예제

서버에서 `IMG2EXCEL_API_KEY`를 설정한 후 실행하세요. Python은 `pip install requests`가 필요하고, Node.js는 20 이상을 사용해야 합니다.


### cURL

```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: image-to-excel-001" \
  -F "file=@spreadsheet-photo.jpg"
```


### Python

```python
import os
import requests

with open("spreadsheet-photo.jpg", "rb") as image:
    response = requests.post(
        "https://img2excel.net/api/v1/image-to-excel",
        headers={
            "Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}",
            "Idempotency-Key": "spreadsheet-photo-001",
        },
        files={"file": ("spreadsheet-photo.jpg", image, "image/jpeg")},
        timeout=330,
    )

response.raise_for_status()
job = response.json()
print(job["result"]["download_url"])
```


### Node.js

```ts
import { readFile } from 'node:fs/promises';

const file = await readFile('spreadsheet-photo.jpg');
const form = new FormData();
form.set('file', new File([file], 'spreadsheet-photo.jpg', { type: 'image/jpeg' }));

const response = await fetch('https://img2excel.net/api/v1/image-to-excel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMG2EXCEL_API_KEY}`,
    'Idempotency-Key': 'spreadsheet-photo-001',
  },
  body: form,
  signal: AbortSignal.timeout(330_000),
});

if (!response.ok) throw new Error(await response.text());
const job = await response.json();
console.log(job.result.download_url);
```




## 응답

**200 OK** — 변환이 완료되었습니다. `result.download_url`에서 Excel 파일을 다운로드하세요. 예제 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
  }
}
```

**422 Unprocessable Entity** — 변환에 실패했습니다. 응답에는 작업 ID, `status: "failed"`, `error.code`, `error.message`가 포함됩니다. 크레딧은 차감되지 않습니다.

멱등성 키에 해당하는 기존 작업이 있으면 `Idempotent-Replayed: true`를 반환합니다. 완료된 작업은 `200`, 만료된 결과는 `410`을 반환합니다. 원래 작업이 대기 중이거나 처리 중이면 재시도는 `202`와 `Location` 헤더를 반환합니다. 새 변환을 만들지 말고 해당 URL을 조회하세요.

전체 응답 필드는 [작업 및 오류](https://img2excel.net/ko/docs/api/jobs)를 참조하세요. 같은 변환 유형의 동기·비동기 요청은 작업 기록, 계정 제한, 멱등성 키를 공유합니다.

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

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

완료를 기다리지 않으려면 `POST /api/v1/image-to-excel/jobs`를 사용하세요. 업로드 필드와 인증 방법은 같습니다. 새 작업은 `202`, 작업 ID, `Location`을 반환합니다. `GET /api/v1/jobs/{job_id}`를 2~3초마다 조회하고 `succeeded`, `failed` 또는 `expired`가 되면 중지하세요. 성공 시 `result.download_url`에서 다운로드하세요. [작업 및 오류](https://img2excel.net/ko/docs/api/jobs)를 참조하세요.

---

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