Skip to main content

# OCR API

OCR is exposed as an HTTP API through the Cloud APIM - OCR backend plugin. The same handler is also available through the unified OpenAI Compatible API plugin on the `POST /ocr` path.

## Plugin setup​

Add the Cloud APIM - OCR backend plugin to your route:

    {
      "enabled": true,
      "plugin": "cp:otoroshi_plugins.com.cloud.apim.otoroshi.extensions.aigateway.plugins.OpenAICompatOcr",
      "config": {
        "refs": ["ocr-model_xxxxxxxxx"],
        "max_size_upload": 104857600
      }
    }

Parameter | Type | Default | Description
--- | --- | --- | ---
`refs` | array of strings | — | References to OCR model entities
`max_size_upload` | number | `104857600` (100 MB) | Maximum upload file size in bytes (multipart requests)

When several OCR models are referenced, the first one is used by default. To target a specific model entity, set the `provider` field to its id in the request body.

## Request​

The endpoint accepts the document in two transports.

### JSON body (Mistral-style)​

    curl https://my-ocr-endpoint.example.com/ocr \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OTOROSHI_API_KEY" \
      -d '{
        "model": "alpha-digit-max",
        "document": {
          "type": "document_url",
          "document_url": "https://example.com/scan.pdf"
        }
      }'

The document can be provided in any of the following ways:

Form | Example
--- | ---
Remote URL (Mistral-style object) | `{ "document": { "type": "document_url", "document_url": "https://..." } }`
Image URL (Mistral-style object) | `{ "document": { "type": "image_url", "image_url": { "url": "https://..." } } }`
Flat URL field | `{ "document_url": "https://..." }` or `{ "image_url": "https://..." }`
Base64 string | `{ "image_base64": "JVBERi0..." }` or `{ "document_base64": "..." }`
Base64 data-uri | `{ "document_url": "data:application/pdf;base64,JVBERi0..." }`

### Request parameters (JSON)​

Parameter | Type | Description
--- | --- | ---
`model` | string | The OCR model to use. Defaults to the model configured on the entity.
`document` | object | The document reference (`type` + `document_url` / `image_url`)
`document_url` / `image_url` | string | A remote url or base64 data-uri (alternative to `document`)
`image_base64` / `document_base64` | string | The document content, base64 encoded
`content_type` | string | The document content type (e.g. `application/pdf`, `image/png`) — useful to route image vs document with Mistral
`pages` | array of numbers | Optional list of page indices to process (provider dependent)
`pdf_password` | string | Optional password for protected PDFs (AlphaEdge)
`provider` | string | Optional OCR model entity id to target when several `refs` are configured

### Multipart file upload​

The dedicated plugin also accepts a raw `multipart/form-data` file upload. Send the file in a field named `image` (`file` and `document` are also accepted):

    curl https://my-ocr-endpoint.example.com/ocr \
      -H "Authorization: Bearer $OTOROSHI_API_KEY" \
      -F "image=@scan.pdf" \
      -F "model=alpha-digit-max"

Any extra form fields (e.g. `model`, `pdf_password`, `provider`) are read alongside the file.

## Response​

The response follows a simplified, Mistral-inspired shape:

    {
      "model": "alpha-digit-max",
      "text": "The full extracted text...",
      "pages": [
        { "index": 0, "markdown": "The full extracted text..." }
      ],
      "usage_info": {
        "pages_processed": 1
      }
    }

Field | Type | Description
--- | --- | ---
`model` | string | The model that produced the result
`text` | string | The full extracted text (all pages concatenated)
`pages` | array | Per-page results, each with `index` and `markdown`
`usage_info.pages_processed` | number | Number of pages processed

## Unified API​

When using the unified OpenAI Compatible API plugin, add your OCR model entities to `ocr_model_refs` and call the `POST /ocr` path. The request and response formats are identical to the dedicated plugin.

    {
      "plugin": "cp:otoroshi_plugins.com.cloud.apim.otoroshi.extensions.aigateway.plugins.OpenAiCompatApi",
      "config": {
        "ocr_model_refs": ["ocr-model_xxxxxxxxx"],
        "max_size_upload": 104857600
      }
    }