Name: dots.ocr API: Document OCR with Confidence Scores
Brand: magicapi
SKU: api-magicapi-multilingual-document-parser-mind-ware-dots-ocr-with-confidence
Availability: InStock
Author: API Market

Shashank Agarwal

# 📄 Document OCR and Layout Parsing API (mind-ware dots.ocr with Confidence)

## Overview
dots.ocr with Confidence, published by mind-ware, is a multilingual document parser that combines layout detection and content recognition in one model. This version can also return a confidence score for each word, so you can find the parts of a page the model was unsure about.

Send a document image in `image` and pick a `prompt_mode`: full layout parsing with text, layout only, plain OCR, OCR of a single region (`grounding_ocr` with a `bbox`), or your own instruction (`custom`). The result is a JSON object whose `text` field holds the parsed content; with `return_confidence` set to `true` it also includes per-word confidences and summary statistics.

## Features
- **Layout and text in one call**: the default `layout_all` mode returns page elements with their bounding boxes, categories (for example `Section-header`, `Text`, `List-item`) and text.
- **Five prompt modes**: `layout_all` (default), `layout_only`, `ocr_only`, `grounding_ocr` and `custom`.
- **Region OCR**: with `prompt_mode` `grounding_ocr`, set `bbox` to `x1,y1,x2,y2` in image pixels to read only that region.
- **Custom instructions**: with `prompt_mode` `custom`, send your own instruction in `custom_prompt`.
- **Word confidence**: set `return_confidence` to `true` to get `word_confidences`, `avg_confidence`, `word_count` and `low_confidence_count` (words below `confidence_threshold`, default 0.5).
- **Long documents**: `max_tokens` runs from 256 to 32768 (default 8192).

## Use Cases
1. **Document digitization**: turn scans and photos of pages into structured text with section headers and list items.
2. **Label and form reading**: read one region of a page, such as the directions block of a product label in the example.
3. **Human review routing**: send only pages with a low `avg_confidence` or many low-confidence words to a person for checking.
4. **Layout analysis**: get the bounding boxes and categories of page elements with `layout_only` for downstream processing.

## Visual Examples
### Example Input
A photo of a product label, read with `prompt_mode` `grounding_ocr` inside the region `400,514,850,640` and with `return_confidence` turned on.

![Input image: a product label with a Directions section](https://blog.api.market/wp-content/uploads/2026/10/dots-ocr-with-confidence-input-api-market.jpg)

```json
{
  "bbox": "400,514,850,640",
  "image": "https://blog.api.market/wp-content/uploads/2026/10/dots-ocr-with-confidence-input-api-market.jpg",
  "top_p": 0.9,
  "max_tokens": 8192,
  "prompt_mode": "grounding_ocr",
  "temperature": 0.1,
  "custom_prompt": "",
  "return_confidence": true,
  "confidence_threshold": 0.5
}
```

### Example Output
The model found 4 elements in the region (a section header, a text block and two list items) with an average confidence of 0.8893; 19 of 166 words were below the 0.5 threshold. The output, with `word_confidences` shortened to its first 4 entries:

```json
{
  "avg_confidence": 0.8893,
  "bbox_used": [
    400,
    514,
    850,
    640
  ],
  "low_confidence_count": 19,
  "prompt_mode": "grounding_ocr",
  "text": "[{\"bbox\": [448, 513, 528, 535], \"category\": \"Section-header\", \"text\": \"### Directions\"}, {\"bbox\": [448, 533, 824, 565], \"category\": \"Text\", \"text\": \"For sunscreen use: • apply generously 15 minutes before sun exposure • reapply: • after 80 minutes of swimming or sweating • immediately after towel drying • at least every 2 hours\"}, {\"bbox\": [448, 563, 832, 624], \"category\": \"List-item\", \"text\": \"• **Sun Protection Measures.** Spending time in the sun increases your risk of skin cancer and early skin aging. To decrease this risk, regularly use a sunscreen with a Broad Spectrum SPF value of 15 or higher and other sun protection measures including: • limit time in the sun, especially from 10 a.m. - 2 p.m. • wear long-sleeved shirts, pants, hats and sunglasses\"}, {\"bbox\": [448, 622, 640, 638], \"category\": \"List-item\", \"text\": \"• children under 6 months of age: Ask a doctor\"}]",
  "word_confidences": [
    {
      "confidence": 0.9999,
      "word": "[{\"bbox\":"
    },
    {
      "confidence": 0.0339,
      "word": "[448"
    },
    {
      "confidence": 1,
      "word": ","
    },
    {
      "confidence": 0.1509,
      "word": "513"
    }
  ],
  "word_count": 166
}
```

In the layout modes, `text` is a JSON string, so parse it to get the list of elements. Confidences are computed for each word of that raw string, including bounding box numbers and JSON punctuation, which is why some entries such as `[448` have a low score.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Document image to read (URL) |
| `prompt_mode` | string | No | `layout_all` | `layout_all`, `layout_only`, `ocr_only`, `grounding_ocr`, `custom` | What to extract: `layout_all` (layout and text), `layout_only` (layout without text), `ocr_only` (text only), `grounding_ocr` (text inside `bbox`) or `custom` (uses `custom_prompt`) |
| `custom_prompt` | string | No | `""` |  | Your own instruction. Used with `prompt_mode` `custom` |
| `bbox` | string | No | `""` |  | Region to read as `x1,y1,x2,y2` in image pixels. Used with `prompt_mode` `grounding_ocr` |
| `max_tokens` | integer | No | `8192` | `256` to `32768` | Maximum number of tokens to generate |
| `return_confidence` | boolean | No | `false` |  | Return per-word confidence scores and summary statistics |
| `confidence_threshold` | number | No | `0.5` | `0` to `1` | Words with a confidence below this value (0 to 1) are counted as low confidence |
| `temperature` | number | No | `0.1` | `0` to `2` | Sampling temperature. Ignored when `return_confidence` is `true` |
| `top_p` | number | No | `0.9` | `0` to `1` | Top-p sampling |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.014 per API unit.
- **1 API unit = 1 request with up to 12 seconds of processing.** A request that takes longer bills one more unit for each started block of 12 seconds (for example, 13 seconds of processing is 2 units).
- Every `prompt_mode` and input setting is billed the same way; large pages with a high `max_tokens` can take longer and use more units.
- **Example cost**: the example request took 5.64 seconds of processing, which is 1 API unit = **$0.014**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/multilingual-document-parser-mind-ware-dots-ocr-with-confidence`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/multilingual-document-parser-mind-ware-dots-ocr-with-confidence/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "91ce60f4885d7ca6e095755e25d0f9ff2bcfe963c816937ece4be50d811f26c4",
    "input": {
      "bbox": "400,514,850,640",
      "image": "https://blog.api.market/wp-content/uploads/2026/10/dots-ocr-with-confidence-input-api-market.jpg",
      "top_p": 0.9,
      "max_tokens": 8192,
      "prompt_mode": "grounding_ocr",
      "temperature": 0.1,
      "custom_prompt": "",
      "return_confidence": true,
      "confidence_threshold": 0.5
    }
  }'
```

Response (201 Created):
```json
{
  "id": "mxybznzs6xrmw0d1d16bj17bm4",
  "version": "91ce60f4885d7ca6e095755e25d0f9ff2bcfe963c816937ece4be50d811f26c4",
  "status": "starting",
  "created_at": "2026-10-23T10:27:17.598Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/multilingual-document-parser-mind-ware-dots-ocr-with-confidence/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "mxybznzs6xrmw0d1d16bj17bm4",
  "status": "succeeded",
  "output": {
    "avg_confidence": 0.8893,
    "bbox_used": [
      400,
      514,
      850,
      640
    ],
    "low_confidence_count": 19,
    "prompt_mode": "grounding_ocr",
    "text": "[{\"bbox\": [448, 513, 528, 535], \"category\": \"Section-header\", \"text\": \"### Directions\"}, {\"bbox\": [448, 533, 824, 565], \"category\": \"Text\", \"text\": \"For sunscreen use: • apply generously 15 minutes before sun exposure • reapply: • after 80 minutes of swimming or sweating • immediately after towel drying • at least every 2 hours\"}, {\"bbox\": [448, 563, 832, 624], \"category\": \"List-item\", \"text\": \"• **Sun Protection Measures.** Spending time in the sun increases your risk of skin cancer and early skin aging. To decrease this risk, regularly use a sunscreen with a Broad Spectrum SPF value of 15 or higher and other sun protection measures including: • limit time in the sun, especially from 10 a.m. - 2 p.m. • wear long-sleeved shirts, pants, hats and sunglasses\"}, {\"bbox\": [448, 622, 640, 638], \"category\": \"List-item\", \"text\": \"• children under 6 months of age: Ask a doctor\"}]",
    "word_confidences": [
      {
        "confidence": 0.9999,
        "word": "[{\"bbox\":"
      },
      {
        "confidence": 0.0339,
        "word": "[448"
      },
      {
        "confidence": 1,
        "word": ","
      },
      {
        "confidence": 0.1509,
        "word": "513"
      }
    ],
    "word_count": 166
  },
  "error": null,
  "created_at": "2026-10-23T10:27:17.598Z",
  "started_at": "2026-10-23T10:28:14.255Z",
  "completed_at": "2026-10-23T10:28:19.896Z"
}
```

`output` is an object. `text` holds the parsed content (a JSON string of page elements in the layout modes) and `prompt_mode` echoes the mode used. `bbox_used` is the region read in `grounding_ocr` mode. `word_confidences`, `avg_confidence`, `word_count` and `low_confidence_count` are filled only when `return_confidence` is `true`. `word_confidences` is shortened above.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image`, a `prompt_mode` that is not in the list or a `max_tokens` below 256.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/multilingual-document-parser-mind-ware-dots-ocr-with-confidence";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "91ce60f4885d7ca6e095755e25d0f9ff2bcfe963c816937ece4be50d811f26c4", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "bbox": "400,514,850,640",
  "image": "https://blog.api.market/wp-content/uploads/2026/10/dots-ocr-with-confidence-input-api-market.jpg",
  "top_p": 0.9,
  "max_tokens": 8192,
  "prompt_mode": "grounding_ocr",
  "temperature": 0.1,
  "custom_prompt": "",
  "return_confidence": true,
  "confidence_threshold": 0.5
}).then((output) => console.log(output.text));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/multilingual-document-parser-mind-ware-dots-ocr-with-confidence"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "91ce60f4885d7ca6e095755e25d0f9ff2bcfe963c816937ece4be50d811f26c4", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "bbox": "400,514,850,640",
    "image": "https://blog.api.market/wp-content/uploads/2026/10/dots-ocr-with-confidence-input-api-market.jpg",
    "top_p": 0.9,
    "max_tokens": 8192,
    "prompt_mode": "grounding_ocr",
    "temperature": 0.1,
    "custom_prompt": "",
    "return_confidence": True,
    "confidence_threshold": 0.5
})
print(output["text"])
```

## FAQ
- **Which `prompt_mode` should I use?**
  - Use `layout_all` (the default) for structured text with element types and positions, `ocr_only` for plain text, `layout_only` for element positions without text, `grounding_ocr` with `bbox` to read one region, and `custom` with `custom_prompt` for your own instruction.
- **How do I read the parsed elements?**
  - In the layout modes `output.text` is a JSON string. Parse it (`JSON.parse(output.text)` or `json.loads(output["text"])`) to get a list of elements, each with `bbox`, `category` and `text`.
- **What coordinates does `bbox` use?**
  - `x1,y1,x2,y2` in pixels of the input image, from the top-left corner. The example read the region `400,514,850,640`.
- **How should I use the confidence scores?**
  - Set `return_confidence` to `true` and check `avg_confidence` and `low_confidence_count`. Scores cover every token of the raw `text`, including JSON punctuation and box numbers, so judge the words of the extracted text rather than the structural parts.
- **How much does a request cost?**
  - $0.014 per request for up to 12 seconds of processing. The example took 5.64 seconds and cost $0.014.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Extract text and layout from document images with dots.ocr, read single regions and get per-word confidence scores to flag uncertain text.