OCR & Layout

Use OCR when you need line text with geometry. Use Layout when you need ordered page components such as headers, text blocks, tables, and figures.

Request contracts

POST /v1/ocr accepts:

{
  "input": {"file_id": "file_123"},
  "execution_mode": "sync",
  "language": "auto",
  "mode": "regular"
}

POST /v1/layout accepts:

{
  "input": {"file_id": "file_123"},
  "execution_mode": "sync",
  "mode": "non_overlapping"
}

cURL

curl -sS -X POST "https://api.docspeed.ai/v1/ocr" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"file_id": "file_123"},
    "execution_mode": "sync",
    "language": "auto",
    "mode": "regular"
  }'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/v1/layout",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "input": {"file_id": "file_123"},
        "execution_mode": "sync",
        "mode": "non_overlapping",
    },
    timeout=600,
)
response.raise_for_status()
print(response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/v1/ocr", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { file_id: "file_123" },
    execution_mode: "sync",
    language: "auto",
    mode: "regular",
  }),
});

console.log(await response.json());

Example OCR response fragment

{
  "language": "auto",
  "mode": "regular",
  "pages": [
    {
      "page_index": 0,
      "width": 1200,
      "height": 1600,
      "text": "Invoice\nTotal Due 1240.00",
      "lines": [
        {
          "bbox_id": "p1_line_1",
          "text": "Total Due 1240.00",
          "page_index": 0,
          "bbox": [80, 320, 500, 346]
        }
      ]
    }
  ]
}

Example Layout response fragment

{
  "mode": "non_overlapping",
  "pages": [
    {
      "page_index": 0,
      "width": 1200,
      "height": 1600,
      "image_ref": "/api/v1/files/file_123/pages/0/image",
      "components": [
        {
          "id": "p1_component_1",
          "reading_order_rank": 1,
          "type": "header",
          "bbox": [80, 90, 520, 150],
          "score": 0.98
        }
      ]
    }
  ]
}

Production notes

• Keep language: "auto" unless you have a known language constraint.
• Use mode: "regular" for production OCR unless you intentionally selected another OCR mode.
• Use mode: "non_overlapping" for compact layout components in reading order.
• Use Parse when you need the combined markdown plus public regions[] and chunks[] contract.