Read a document

POSThttps://api.paxalabs.com/v1/ocrOpen in playground

POST /v1/ocr reads a PDF or image and returns its text as Markdown or typed layout blocks, one entry per page. Charged in credits per page before reading, refunded on failure.

View as Markdown
# Encode without line wrapping: wrapped base64 breaks the JSON string.
DOC=$(base64 < invoice.pdf | tr -d '\n')
# --max-time covers a multi-page document; curl defaults to no limit.
curl -X POST https://api.paxalabs.com/v1/ocr \
  --max-time 300 \
  -H "Authorization: Bearer $PAXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"document\": \"$DOC\", \"model\": \"paxa-ocr-lite-v1\"}"
{
  "pages": [
    {
      "page": 1,
      "markdown": "# ใบเสร็จรับเงิน\n\nร้านข้าวแกงบ้านสวน สาขาสีลม\n\n| รายการ | จำนวน | ราคา |\n| --- | --- | --- |\n| ข้าวแกงเขียวหวานไก่ | 1 | 60 |\n| น้ำเปล่า | 1 | 10 |\n\nรวมทั้งสิ้น 70 บาท"
    }
  ],
  "usage": {
    "pages": 1,
    "credits": 6.5
  }
}

Send the file as base64 in document. An image counts as one page. The OCR guide covers the two output shapes, the block types, and the page and size limits.

Headers#

authorizationBearer pxa_...Required

Authorization: Bearer pxa_... (recommended).

x-api-keypxa_...

Alternative to the Authorization header. Ignored when Authorization is present.

idempotency-keystring

Makes a retry safe. Two requests carrying the same key charge once and synthesize the same content. One request per key runs at a time. A concurrent duplicate answers 409 idempotency_in_flight. Reuse a key only to retry an identical request. A changed payload is rejected with 422. Accepts up to 200 printable ASCII characters.

1 to 200 characterspattern ^[!-~]+$

Authentication

Body#

documentstringRequired

The document to read, as the base64 encoding of a PDF, PNG, JPEG, or WebP file. An image counts as one page. Cost is 6.5 credits per page, charged before reading and refunded automatically when reading fails. A PDF may carry up to 50 pages, and more answers 400 too_many_pages. The decoded file may be up to 10,485,760 bytes, and larger answers 413 document_too_large. A file that cannot be read as one of the four formats answers 400 document_invalid, and a PDF that needs a password to open answers 400 document_password_required. GET /v1/models reports the ceilings as max_pages and max_bytes.

1 to 15,900,000 characters
modelstringRequired

OCR model id, for example paxa-ocr-lite-v1. GET /v1/models lists the served catalog.

1 to 100 charactersExample "paxa-ocr-lite-v1"
output"markdown" or "structured"

Shape of the result. "markdown", the default, returns each page as GitHub-flavored Markdown. "structured" returns each page as typed layout blocks, for callers that feed the reading into a pipeline.

Default "markdown"

Response#

The recognized document.

pagesarray of objectsRequired

One entry per page of the document, in page order.

Show properties
pages[].pageintegerRequired

Page number, starting at 1. An image request has exactly one page.

pages[].markdownstring

The page's content as GitHub-flavored Markdown, in reading order. Present when output is "markdown". Join pages with a blank line to rebuild the document.

pages[].blocksarray of objects

The page's content as typed blocks in reading order. Present when output is "structured".

Show properties
pages[].blocks[].typestringRequired

What the block is: "heading", "paragraph", "list", "table", or "figure". Blocks arrive in reading order.

pages[].blocks[].textstring

The block's text. Present on "heading", "paragraph", and "figure" blocks. A figure's text is its caption or nearby label, and is empty when it has none.

pages[].blocks[].levelinteger

Heading depth, starting at 1 for the most prominent. Present on "heading" blocks.

pages[].blocks[].itemsarray of strings

The list entries in order. Present on "list" blocks.

pages[].blocks[].rowsarray of array of stringss

The table cells as rows of column values, first row first. Present on "table" blocks.

usageobjectRequired

What the request was billed for.

Show properties
usage.pagesintegerRequired

Pages this request was billed for.

usage.creditsnumberRequired

What this delivery cost, in credits, exact to a hundredth. An idempotent replay reports the ORIGINAL request's charge, since that one charge is what paid for this delivery too; your balance moves only once.

Errors#

400validationThe request body or headers failed validation against the endpoint schema.
400unknown_modelThe model field does not name a served model.
400document_invalidThe document field could not be read as a PDF, PNG, JPEG, or WebP file. A damaged or truncated PDF answers this code. Nothing was charged.
400document_password_requiredThe PDF needs a password to open. A PDF that carries permissions-only encryption, the kind that opens without being asked for a password, is read normally. Nothing was charged.
413document_too_largeThe decoded document exceeds the model's size ceiling. Nothing was charged.
400too_many_pagesThe document has more pages than the model's per-request ceiling. Nothing was charged.
401unauthorizedThe request carried no API key, or the key is invalid or disabled.
402insufficient_creditsThe account does not have enough credits for this request. Nothing was charged.
403key_limitThis API key reached its spending cap. Nothing was charged.
409idempotency_in_flightAnother request with this Idempotency-Key is in flight right now.
409idempotency_refundedThe original request under this Idempotency-Key failed and was refunded.
422idempotency_mismatchThis Idempotency-Key was already used for a different request.
422content_blockedThe upstream safety system declined to process this content. The charge was refunded.
429rate_limitedRequests per minute for the plan are exhausted. One window covers the whole account, across every product and every key.
429concurrency_limitedThe account holds the plan's full count of concurrent requests for this product. Nothing was charged. Each product is limited separately, and an open live connection holds one speech slot.
500internalRequest state was inconsistent on the server.
502provider_errorModel inference failed after the request was charged.
503provider_unavailableThe model behind this endpoint is not available right now. Nothing was charged.