# Quick Start

Make your first API call and download an Excel file.

Canonical documentation: https://img2excel.net/docs/api/getting-started

The IMG2Excel API converts a table image into an editable Excel workbook. We recommend the synchronous endpoint: upload an image, wait for conversion, then download the XLSX file from the returned URL. Asynchronous endpoints remain available.

| Parameter | Value |
| --- | --- |
| Base URL | `https://img2excel.net` |
| Authentication | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| API access | Business or Professional credit package |
| Input | One PNG, JPG, or JPEG image, up to 4MB |
| Output | An editable `.xlsx` file |

## 1. Set Your API Key

Copy your key from [API settings](https://img2excel.net/settings/api) and store it in a server-side environment variable:

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

Keep the key private. Do not put it in browser code or a public repository.

## 2. Upload a Table Image

Choose the endpoint that matches your image:

| Image | Endpoint |
| --- | --- |
| Printed table, screenshot, or scanned spreadsheet | [Image to Excel](https://img2excel.net/docs/api/image-to-excel) |
| Handwritten table, log, or record | [Handwriting to Excel](https://img2excel.net/docs/api/handwriting-to-excel) |

The example below submits a printed table. Replace `table.png` with your image path. For handwriting, use `/api/v1/handwriting-to-excel` instead.

```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"
```

Use a different `Idempotency-Key` for each new image. Reuse it only when retrying the same upload.

The synchronous request returns **200 OK** when conversion finishes, including `result.download_url`. The URL below is an example; use the one returned by your request.

```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
  }
}
```

The synchronous endpoint waits for conversion to complete. Set your HTTP client timeout to 330 seconds. If the connection times out, retry with the same `Idempotency-Key`; do not use a new key unless you intend to start another conversion.

## 3. Download the Excel File

Copy `result.download_url` from the successful response:

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

The download URL is valid for 15 minutes. Results are retained for 24 hours after completion; retrieve the job again for a fresh URL during that period. Failed conversions do not consume credits.

## Asynchronous Conversion (Optional)

For background processing, append `/jobs` to the conversion endpoint. A new job returns `202` with its ID and a `Location` header. Poll that URL every 2–3 seconds until the status is `succeeded`, `failed`, or `expired`. See [Jobs and Errors](https://img2excel.net/docs/api/jobs) for the polling script.

A synchronous conversion failure returns `422` with `error.code` and `error.message`. A retry with the same idempotency key returns the original job; if it is still running, the response is `202`, and you can query its `Location` URL. An expired result returns `410`.

## Use an AI Coding Assistant

Select **Copy to AI** above and paste the instructions into ChatGPT, Claude, Gemini, Cursor, or another assistant. Tell it your server-side language and whether you need printed-table or handwriting conversion. Each endpoint page also provides its own copy action and Python / Node.js examples.

For the full API contract, use the [OpenAPI specification](https://img2excel.net/api/openapi.json) or [complete API context](https://img2excel.net/docs/api/llms-full.txt).

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Complete API documentation: https://img2excel.net/docs/api/llms-full.txt