API Reference

OCR

Extract normalised Markdown and text from document images through a stable API.

A stable OCR contract

OCR providers do not share a portable API. Inferada therefore defines /v1/ocr as its own contract rather than presenting it as an OpenAI-compatible endpoint.

The gateway normalises provider-specific prompting and output. Responses include the selected model ID and extracted text, so backend changes do not require changes to your upload flow.

Extract a document image

POST/v1/ocr

Scopeocr

Upload one JPEG, PNG, or WebP document image (maximum 20 MB).

Request

filerequiredfile: JPEG, PNG, or WebP document image, up to 20 MB.
modelstring: Optional stable OCR model id. Omit it to use the service default.
service_iduuid: Optional OCR service override. Omit it to use the organisation default.

bash

curl https://api.inferada.com/v1/ocr \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -F "file=@invoice.png" \
  -F "model=ocr"

Response · 200

objectstring: Always "ocr.result".
modelstring: Stable Inferada model id selected for this request.
textstring: Normalised document Markdown/text.
pagesarray: Page-indexed output. Image uploads currently produce one page; the array keeps the contract ready for PDF/multi-page ingestion.
usageobject: Upstream prompt, completion, and total token counts.
inferadaobject: Additive Inferada metadata: request correlation and gateway/upstream timing.

json

{
  "id": "ocr_019...",
  "object": "ocr.result",
  "created": 1786878900,
  "model": "ocr",
  "text": "# Invoice\n\nInvoice number: 1042...",
  "pages": [
    { "index": 0, "text": "# Invoice\n\nInvoice number: 1042..." }
  ],
  "usage": {
    "prompt_tokens": 1240,
    "completion_tokens": 184,
    "total_tokens": 1424
  },
  "inferada": {
    "request_id": "019...",
    "timings": { "upstream_ms": 812, "total_ms": 829 }
  }
}

Errors

A 400 response means the image type or requested model is unsupported. A 404 response means no OCR service is configured. Files larger than 20 MB return 413. A 502 response means the OCR service failed or returned no usable content.