> For the complete documentation index, see [llms.txt](https://docs.solvora.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solvora.xyz/welcome-developer.md).

# Welcome, Developer

Here you will find basic information along with API documentation for the OCR solver.

## Overview

The OCR API lets you submit images and receive extracted text back. All requests are handled asynchronously. You submit an image, receive a `task_id`, and poll for the result.

{% hint style="info" %}
You will need a valid API key to use any endpoint. Contact your administrator to obtain one.
{% endhint %}

## Authentication

Every request requires your API key as a query parameter:

```
?api=YOUR_API_KEY
```

## Endpoints

### Check Balance

<mark style="color:green;">`GET`</mark> `/api/balance`

Returns your remaining solve credits and usage in the last 24 hours.

**Query Parameters**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `api`     | string | ✅ Yes    | Your API key |

**Example Request**

```http
GET /api/balance?api=YOUR_API_KEY
```

**Example Response**

```json
{
  "status": "ok",
  "solves": 950,
  "24h": 50
}
```

**Response Fields**

| Field    | Type    | Description                                |
| -------- | ------- | ------------------------------------------ |
| `status` | string  | `"ok"` if the request succeeded            |
| `solves` | integer | Total solve credits remaining              |
| `24h`    | integer | Number of solves used in the last 24 hours |

### Submit Image for OCR

<mark style="color:blue;">`POST`</mark> `/api/ocr/solve`

Upload an image to be processed. Returns a `task_id` to use when polling for the result.

**Query Parameters**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `api`     | string | ✅ Yes    | Your API key |

**Request Body**

| Field   | Type | Required | Description                      |
| ------- | ---- | -------- | -------------------------------- |
| `image` | file | ✅ Yes    | Image file (multipart/form-data) |

{% hint style="info" %}
Common formats like PNG, JPG, and BMP are supported.
{% endhint %}

**Example Request**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://<host>/api/ocr/solve?api=YOUR_API_KEY" \
     -F "image=@/path/to/your/image.png"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

with open("image.png", "rb") as f:
    response = requests.post(
        "https://<host>/api/ocr/solve",
        params={"api": "YOUR_API_KEY"},
        files={"image": f}
    )

data = response.json()
task_id = data["task_id"]
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const form = new FormData();
form.append("image", fileInput.files[0]);

const response = await fetch("/api/ocr/solve?api=YOUR_API_KEY", {
  method: "POST",
  body: form,
});

const { task_id } = await response.json();
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "ok",
  "result": "in_process",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "solves": 949
}
```

**Response Fields**

| Field     | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `status`  | string  | `"ok"` if the task was accepted         |
| `result`  | string  | `"in_process"` while OCR is running     |
| `task_id` | string  | Use this to retrieve your result        |
| `solves`  | integer | Remaining credits after this submission |

{% hint style="warning" %}
One solve credit is deducted per successful OCR completion. Tasks and uploaded images are automatically deleted after **30 seconds** — retrieve your result promptly.
{% endhint %}

### Get OCR Result

<mark style="color:green;">`GET`</mark> `/api/ocr/result/{task_id}`

Poll this endpoint with the `task_id` from the submit step to retrieve your OCR result.

**Path Parameters**

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `task_id` | string | ✅ Yes    | The task ID returned from the submit endpoint |

**Example Request**

```http
GET /api/ocr/result/d290f1ee-6c54-4b01-90e6-d701748f0851
```

**Example Responses**

{% tabs %}
{% tab title="In Progress" %}

```json
{
  "status": "ok",
  "result": "in_process",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": null,
  "solves": 949
}
```

{% endtab %}

{% tab title="Completed" %}

```json
{
  "status": "ok",
  "result": "Hello, this is the extracted text from the image.",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": 1.23,
  "solves": 949
}
```

{% endtab %}

{% tab title="Failed" %}

```json
{
  "status": "fail",
  "result": "subprocess_timed_out",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": null,
  "solves": 949
}
```

{% endtab %}
{% endtabs %}

**Response Fields**

| Field     | Type    | Description                                             |
| --------- | ------- | ------------------------------------------------------- |
| `status`  | string  | `"ok"` for success, `"fail"` if something went wrong    |
| `result`  | string  | Extracted text, `"in_process"`, or an error message     |
| `task_id` | string  | The task identifier                                     |
| `time`    | float   | Processing time in seconds (`null` if not yet complete) |
| `solves`  | integer | Your remaining credits                                  |

{% hint style="info" %}
Poll every 1–2 seconds until `result` is no longer `"in_process"`. Tasks expire after **30 seconds** — after that, this endpoint returns `404 Not Found`.
{% endhint %}

## Error Reference

| HTTP Status | Detail                      | Meaning                                                  |
| ----------- | --------------------------- | -------------------------------------------------------- |
| `401`       | `Invalid API key`           | Your API key is wrong or does not exist                  |
| `402`       | `No solves remaining`       | You have run out of credits — contact your administrator |
| `404`       | `Task not found or expired` | The task has expired (30s limit) or the ID is incorrect  |

## Quick Start

Here's the typical end-to-end flow:

{% stepper %}
{% step %}

### Step 1 — Check your balance

```http
GET /api/balance?api=YOUR_KEY
```

{% endstep %}

{% step %}

### Step 2 — Submit your image

```bash
curl -X POST "/api/ocr/solve?api=YOUR_KEY" -F "image=@image.png"
# Save the returned task_id
```

{% endstep %}

{% step %}

### Step 3 — Poll for the result

```bash
curl "/api/ocr/result/{task_id}"
# Repeat every 1-2 seconds until result != "in_process"
```

{% endstep %}

{% step %}

### Step 4 — Use the extracted text

The OCR output will be in the `result` field of the response.
{% endstep %}
{% endstepper %}